github/github-spec-kit
1
0
Fork 0
mirror of https://github.com/github/spec-kit.git synced 2026-07-06 05:53:12 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(integration): update Kimi integration for Kimi Code CLI (#2979)

Browse Source 
* feat(integration): update Kimi integration for Kimi Code CLI

Update the Kimi integration to target the new Kimi Code CLI
(MoonshotAI/kimi-code) layout:

- Change skills directory from .kimi/skills/ to .kimi-code/skills/
- Change context file from KIMI.md to AGENTS.md
- Extend --migrate-legacy to move old .kimi/skills/ installs and
  migrate KIMI.md user content to AGENTS.md
- Clean up leftover legacy .kimi/skills/ directories on teardown
- Update devcontainer installer to @moonshot-ai/kimi-code
- Update docs and tests

Relates to #1532

* fix(integration): align Kimi dispatch and harden legacy migration

- Override build_command_invocation to emit /skill:speckit-<stem>
  so dispatched commands match Kimi Code CLI's native slash syntax.
- Skip symlinked .kimi/skills directories during legacy migration
  and teardown to avoid operating on files outside the project.
- Remove kimi from the multi-install-safe integrations table.
- Add tests for command invocation and symlink safety.

* fix(integration): resolve custom context markers in Kimi legacy migration

Use IntegrationBase._resolve_context_markers() when migrating legacy
KIMI.md content so that projects with customized context_markers in
.specify/extensions/agent-context/agent-context-config.yml have the
managed section stripped with the correct markers instead of the
hard-coded defaults.

Adds a test verifying custom markers are respected during
--migrate-legacy.

* fix(integration): harden Kimi legacy migration against symlinked paths

* fix(kimi): guard symlinked SKILL.md during migration and teardown

* docs(kimi): mention KIMI.md→AGENTS.md migration in --migrate-legacy help

The --migrate-legacy help text listed only the skills directory move and
dotted→hyphenated renaming, but the flag also migrates KIMI.md user content
into AGENTS.md. Align the help with the actual behavior, docs, and tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(kimi): validate legacy migration destination; clarify docstrings

Address Copilot review feedback on PR #2979:

- setup(): gate skills migration on _is_safe_legacy_dir(new_skills_dir)
  as well as the source. base setup() already rejects a destination that
  escapes the project root, but an in-tree symlinked .kimi-code/skills
  (e.g. -> .) could still misdirect the move; this gives the destination
  the same symlink-component protection as the source.
- _migrate_legacy_kimi_dotted_skills: rewrite docstring as a compatibility
  shim describing same-path delegation to _migrate_legacy_kimi_skills_dir.
- test_presets: clarify that the dotted-skill test exercises legacy naming
  under the current .kimi-code/ base, not the legacy .kimi/ location.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(kimi): harden legacy KIMI.md→AGENTS.md context migration

- Skip context-file migration when the agent-context extension is
  disabled, matching upsert/remove_context_section opt-out behavior so
  an opted-out project's KIMI.md/AGENTS.md are left untouched.
- Safely skip (instead of raising) on filesystem edge cases: unreadable
  or non-UTF-8 KIMI.md, and AGENTS.md existing as a non-file/unwritable.
- Refuse to migrate a corrupted managed section (single marker, or end
  before start) so a partial managed block is never copied into
  AGENTS.md; KIMI.md is preserved for manual repair.

Add regression tests for all three cases.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* Fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* Approve fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* chore(kimi): revert CHANGELOG.md edit (auto-generated)

The CHANGELOG is generated from merged PR titles, so a hand-written entry
is redundant; it was also placed under the already-released 0.10.2 section,
which would make those release notes historically inaccurate. Revert to
match main per maintainer feedback.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* test(kimi): skip symlink-safety tests when symlinks are unavailable

The Kimi legacy-migration safety tests create symlinks to assert that
migration/teardown never follow them out of the project. Symlink creation
fails on Windows without the create-symlink privilege and in some restricted
CI sandboxes, so these tests errored during setup instead of skipping.

Wrap every symlink_to() call in a shared _symlink_or_skip() helper that
pytest.skip()s on OSError/NotImplementedError, matching the guard pattern
already used by one of these tests. Verified on Windows: the 6 symlink tests
now skip cleanly (51 passed, 6 skipped) instead of erroring.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(kimi): reject symlinked skills destination before install

Add a destination symlink pre-check in KimiIntegration.setup() before
super().setup() writes any SKILL.md. The base class only rejects a
destination that escapes project_root after resolve(), so an in-tree
symlinked .kimi-code/.kimi-code/skills (e.g. `-> .`) would still
misdirect writes into an unintended in-tree location (./skills/).

Extract the symlink-component walk into a shared _has_symlinked_component()
helper and reuse it from _is_safe_legacy_dir(). Add a regression test.

Also clarify that --migrate-legacy only migrates KIMI.md -> AGENTS.md when
the agent-context extension is enabled, in the CLI help text and the
integration docs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Refactor formatting and simplify logic in Kimi integration

* fix(kimi): reject symlinked target dir during legacy skills migration

When the migration destination already exists, guard against a symlinked
(or non-directory) target_dir before comparing SKILL.md bytes, so the
comparison never follows a link outside the project root. Also skip a
missing/non-file target SKILL.md explicitly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
meymchen
2026-06-25 04:22:08 +08:00
committed by GitHub
parent e12beda5f9
commit dc840f07d0
8 changed files with 877 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

440
src/specify_cli/integrations/kimi/__init__.py
View File

@@ -1,11 +1,13 @@
"""Kimi Code integration — skills-based agent (Moonshot AI).
Kimi uses the ``.kimi/skills/speckit-<name>/SKILL.md`` layout with
Kimi uses the ``.kimi-code/skills/speckit-<name>/SKILL.md`` layout with
``/skill:speckit-<name>`` invocation syntax.
Includes legacy migration logic for projects initialised before Kimi
moved from dotted skill directories (``speckit.xxx``) to hyphenated
(``speckit-xxx``).
Legacy migration covers projects created before Kimi Code CLI moved to
this layout and handles two distinct changes: the directory move from
``.kimi/`` to ``.kimi-code/`` (including the ``KIMI.md`` → ``AGENTS.md``
context file), and the dotted-to-hyphenated skill naming
(``speckit.xxx`` → ``speckit-xxx``).
"""
from __future__ import annotations
@@ -14,7 +16,7 @@ import shutil
from pathlib import Path
from typing import Any
from ..base import IntegrationOption, SkillsIntegration
from ..base import IntegrationBase, IntegrationOption, SkillsIntegration
from ..manifest import IntegrationManifest
@@ -24,19 +26,43 @@ class KimiIntegration(SkillsIntegration):
key = "kimi"
config = {
"name": "Kimi Code",
"folder": ".kimi/",
"folder": ".kimi-code/",
"commands_subdir": "skills",
"install_url": "https://code.kimi.com/",
"requires_cli": True,
}
registrar_config = {
"dir": ".kimi/skills",
"dir": ".kimi-code/skills",
"format": "markdown",
"args": "$ARGUMENTS",
"extension": "/SKILL.md",
}
context_file = "KIMI.md"
multi_install_safe = True
context_file = "AGENTS.md"
multi_install_safe = False
def build_command_invocation(self, command_name: str, args: str = "") -> str:
"""Build Kimi's native skill invocation: ``/skill:speckit-<stem>``.
Kimi Code CLI invokes installed skills with a ``/skill:<name>``
slash command (e.g. ``/skill:speckit-plan``), not the bare
``/speckit-<name>`` form produced by the generic skills base
class. Overriding here keeps ``dispatch_command()`` and workflow
command steps aligned with the ``/skill:`` guidance shown at init
time and in rendered hook invocations.
"""
stem = command_name
if stem.startswith("speckit."):
stem = stem[len("speckit.") :]
invocation = "/skill:speckit-" + stem.replace(".", "-")
if args:
invocation = f"{invocation} {args}"
return invocation
def post_process_skill_content(self, content: str) -> str:
"""Ensure in-skill cross-command references use Kimi's `/skill:` syntax."""
content = super().post_process_skill_content(content)
return content.replace("/speckit-", "/skill:speckit-")
@classmethod
def options(cls) -> list[IntegrationOption]:
@@ -51,7 +77,12 @@ class KimiIntegration(SkillsIntegration):
"--migrate-legacy",
is_flag=True,
default=False,
help="Migrate legacy dotted skill dirs (speckit.xxx → speckit-xxx)",
help=(
"Migrate legacy Kimi installations: "
".kimi/skills/ → .kimi-code/skills/, speckit.xxx → speckit-xxx, "
"and (when the agent-context extension is enabled) "
"KIMI.md user content → AGENTS.md"
),
),
]
@@ -62,64 +93,397 @@ class KimiIntegration(SkillsIntegration):
parsed_options: dict[str, Any] | None = None,
**opts: Any,
) -> list[Path]:
"""Install skills with optional legacy dotted-name migration."""
"""Install skills with optional legacy migration."""
parsed_options = parsed_options or {}
# Run base setup first so hyphenated targets (speckit-*) exist,
# then migrate/clean legacy dotted dirs without risking user content loss.
# Refuse a symlinked destination before any writes occur. base
# setup() only rejects a destination that *escapes* project_root
# after resolve(), so an in-tree symlinked ``.kimi-code`` /
# ``.kimi-code/skills`` (e.g. ``-> .``) would still pass that check
# and misdirect the SKILL.md writes into an unintended in-tree
# location (e.g. ``./skills/``). Reject any symlinked destination
# component up front so this never happens.
new_skills_dir = self.skills_dest(project_root)
if _has_symlinked_component(new_skills_dir, project_root):
raise ValueError(
f"Skills destination {new_skills_dir} contains a symlinked "
f"path component; refusing to install into it."
)
# Run base setup first so new-path targets (speckit-*) exist,
# then migrate/clean legacy dirs without risking user content loss.
created = super().setup(
project_root, manifest, parsed_options=parsed_options, **opts
)
if parsed_options.get("migrate_legacy", False):
skills_dir = self.skills_dest(project_root)
if skills_dir.is_dir():
_migrate_legacy_kimi_dotted_skills(skills_dir)
old_skills_dir = project_root / ".kimi" / "skills"
# Validate both endpoints. base setup() already rejects a
# destination that *escapes* the project root, but an in-tree
# symlinked ``.kimi-code``/``.kimi-code/skills`` (e.g. ``-> .``)
# would still misdirect the move; ``_is_safe_legacy_dir`` rejects
# any symlinked component, giving the destination the same
# protection as the source.
if _is_safe_legacy_dir(old_skills_dir, project_root) and (
_is_safe_legacy_dir(new_skills_dir, project_root)
):
_migrate_legacy_kimi_skills_dir(old_skills_dir, new_skills_dir)
# Mirror upsert/remove_context_section: a disabled agent-context
# extension is a full opt-out, so skip the KIMI.md → AGENTS.md
# migration entirely and leave both files untouched.
if self._agent_context_extension_enabled(project_root):
marker_start, marker_end = self._resolve_context_markers(project_root)
_migrate_legacy_kimi_context_file(
project_root, marker_start=marker_start, marker_end=marker_end
)
return created
def teardown(
self,
project_root: Path,
manifest: IntegrationManifest,
*,
force: bool = False,
) -> tuple[list[Path], list[Path]]:
"""Uninstall Kimi skills and remove leftover legacy directories."""
removed, skipped = super().teardown(project_root, manifest, force=force)
def _migrate_legacy_kimi_dotted_skills(skills_dir: Path) -> tuple[int, int]:
"""Migrate legacy Kimi dotted skill dirs (speckit.xxx) to hyphenated format.
old_skills_dir = project_root / ".kimi" / "skills"
if _is_safe_legacy_dir(old_skills_dir, project_root):
legacy_dirs = sorted(
[*old_skills_dir.glob("speckit-*"), *old_skills_dir.glob("speckit.*")]
)
for legacy_dir in legacy_dirs:
if legacy_dir.is_symlink() or not legacy_dir.is_dir():
continue
if _is_speckit_generated_skill(legacy_dir):
try:
shutil.rmtree(legacy_dir)
removed.append(legacy_dir)
except OSError:
skipped.append(legacy_dir)
try:
old_skills_dir.rmdir()
except OSError:
pass
return removed, skipped
def _has_symlinked_component(path: Path, project_root: Path) -> bool:
"""Return ``True`` when *path* escapes *project_root* or any component is a symlink.
Walks the components strictly between *project_root* and *path*
(including the final one) and reports whether any of them is a symlink.
Components that do not exist yet are not symlinks, so this safely handles
a not-yet-created destination. *project_root* itself is trusted and never
checked. A *path* outside *project_root* is treated as unsafe.
"""
try:
relative = path.relative_to(project_root)
except ValueError:
return True
current = project_root
for part in relative.parts:
current = current / part
if current.is_symlink():
return True
return False
def _is_safe_legacy_dir(path: Path, project_root: Path) -> bool:
"""Return ``True`` when *path* is a real directory safely inside *project_root*.
Legacy migration and cleanup ``shutil.move()`` and ``shutil.rmtree()``
directories, so a symlinked ``.kimi``/``.kimi/skills`` (or one reached
through a symlinked parent) must never be followed: doing so could
relocate or delete content living outside the project tree — or operate
on an unrelated in-tree directory (e.g. ``.kimi -> .`` makes
``.kimi/skills`` resolve to ``./skills``).
Checking only the fully-resolved path is insufficient, because a symlink
pointing elsewhere *inside* the project still resolves to a location under
*project_root*. We therefore reject the path when it is not a directory,
when any component between *project_root* and *path* is a symlink
(including the final component), or when the resolved path escapes the
resolved *project_root*.
"""
if not path.is_dir():
return False
# Reject if any path component below project_root is a symlink (or the
# path escapes project_root). We trust project_root itself, so only
# components strictly under it are checked.
if _has_symlinked_component(path, project_root):
return False
try:
resolved = path.resolve()
root = project_root.resolve()
except OSError:
return False
return resolved == root or root in resolved.parents
def _migrate_legacy_kimi_skills_dir(
old_skills_dir: Path, new_skills_dir: Path
) -> tuple[int, int]:
"""Migrate skills from the legacy ``.kimi/skills/`` directory to ``.kimi-code/skills/``.
Handles both hyphenated (``speckit-xxx``) and dotted (``speckit.xxx``)
legacy directory names. If a target already exists, the legacy dir is
only removed when its ``SKILL.md`` is byte-identical and no extra user
files are present.
Returns ``(migrated_count, removed_count)``.
"""
if not skills_dir.is_dir():
if not old_skills_dir.is_dir():
return (0, 0)
migrated_count = 0
removed_count = 0
for legacy_dir in sorted(skills_dir.glob("speckit.*")):
if not legacy_dir.is_dir():
# Process hyphenated dirs first, then dotted dirs.
legacy_dirs = sorted(old_skills_dir.glob("speckit-*")) + sorted(
old_skills_dir.glob("speckit.*")
)
for legacy_dir in legacy_dirs:
if legacy_dir.is_symlink() or not legacy_dir.is_dir():
continue
if not (legacy_dir / "SKILL.md").exists():
legacy_skill = legacy_dir / "SKILL.md"
# Treat a symlinked SKILL.md as invalid: later read_bytes() would
# otherwise follow it and read content from outside the project.
if legacy_skill.is_symlink() or not legacy_skill.is_file():
continue
suffix = legacy_dir.name[len("speckit."):]
if not suffix:
target_name = _legacy_to_target_name(legacy_dir.name)
if not target_name:
continue
target_dir = skills_dir / f"speckit-{suffix.replace('.', '-')}"
target_dir = new_skills_dir / target_name
# Skip if the legacy dir is already the target dir (same-directory call).
if legacy_dir.resolve() == target_dir.resolve():
continue
if not target_dir.exists():
target_dir.parent.mkdir(parents=True, exist_ok=True)
shutil.move(str(legacy_dir), str(target_dir))
migrated_count += 1
continue
# Target exists — only remove legacy if SKILL.md is identical
# Target exists — only remove legacy if SKILL.md is identical.
# Skip when the target dir or its SKILL.md is a symlink (or the dir is
# not a real directory) so the byte comparison never follows a link
# outside the project. (legacy_skill is already guaranteed to be a real
# file by the guard above.)
if target_dir.is_symlink() or not target_dir.is_dir():
continue
target_skill = target_dir / "SKILL.md"
legacy_skill = legacy_dir / "SKILL.md"
if target_skill.is_file():
try:
if target_skill.read_bytes() == legacy_skill.read_bytes():
has_extra = any(
child.name != "SKILL.md" for child in legacy_dir.iterdir()
)
if not has_extra:
shutil.rmtree(legacy_dir)
removed_count += 1
except OSError:
pass
if target_skill.is_symlink() or not target_skill.is_file():
continue
try:
if target_skill.read_bytes() == legacy_skill.read_bytes():
has_extra = any(
child.name != "SKILL.md" for child in legacy_dir.iterdir()
)
if not has_extra:
shutil.rmtree(legacy_dir)
removed_count += 1
except OSError:
pass
# Remove the legacy skills directory if it is now empty.
try:
old_skills_dir.rmdir()
except OSError:
pass
return (migrated_count, removed_count)
def _legacy_to_target_name(legacy_name: str) -> str:
"""Convert a legacy skill directory name to the modern hyphenated form."""
if legacy_name.startswith("speckit-"):
return legacy_name
if legacy_name.startswith("speckit."):
suffix = legacy_name[len("speckit.") :]
if suffix:
return f"speckit-{suffix.replace('.', '-')}"
return ""
def _is_speckit_generated_skill(skill_dir: Path) -> bool:
"""Return True when *skill_dir* contains a Speckit-generated SKILL.md.
Uses the ``metadata.author`` and ``metadata.source`` fields written by
``SkillsIntegration.setup()`` to avoid deleting user-authored skills.
"""
skill_file = skill_dir / "SKILL.md"
# A symlinked SKILL.md is never treated as Speckit-generated, so teardown
# cleanup never follows it to read frontmatter from outside the project.
if skill_file.is_symlink() or not skill_file.is_file():
return False
try:
content = skill_file.read_text(encoding="utf-8")
except OSError:
return False
if not content.startswith("---"):
return False
parts = content.split("---", 2)
if len(parts) < 3:
return False
try:
import yaml
frontmatter = yaml.safe_load(parts[1])
except Exception:
return False
if not isinstance(frontmatter, dict):
return False
metadata = frontmatter.get("metadata", {})
if not isinstance(metadata, dict):
return False
author = metadata.get("author", "")
source = metadata.get("source", "")
return (
author == "github-spec-kit"
and isinstance(source, str)
and source.startswith("templates/commands/")
)
def _migrate_legacy_kimi_context_file(
project_root: Path,
*,
marker_start: str = IntegrationBase.CONTEXT_MARKER_START,
marker_end: str = IntegrationBase.CONTEXT_MARKER_END,
) -> bool:
"""Migrate user content from legacy ``KIMI.md`` to ``AGENTS.md``.
The Speckit managed section is stripped from ``KIMI.md`` before the
remaining content is appended to ``AGENTS.md``. The legacy file is
deleted if it becomes empty. Returns ``True`` if ``KIMI.md`` was
migrated, ``False`` when the migration is skipped.
The migration is skipped (leaving ``KIMI.md`` untouched) in any of these
cases, so a best-effort legacy cleanup never aborts ``setup()`` or
corrupts ``AGENTS.md``:
- ``KIMI.md`` is a symlink, missing, or unreadable (its target could be
read from outside the project, or it may not be valid UTF-8).
- ``AGENTS.md`` is a symlink (it could redirect the write to a file
outside the project root), exists as a non-file (e.g. a directory),
or is unreadable/unwritable.
- ``KIMI.md`` has a corrupted managed section — only one marker is
present, or the end marker precedes the start. Stripping is only done
when both markers are present and well-ordered, so a partial managed
block is never copied into ``AGENTS.md``; the user repairs it manually.
"""
legacy_path = project_root / "KIMI.md"
if legacy_path.is_symlink() or not legacy_path.is_file():
return False
target_path = project_root / "AGENTS.md"
# Never follow a symlinked target, and never treat an existing non-file
# (e.g. a directory) as a writable context file.
if target_path.is_symlink() or (target_path.exists() and not target_path.is_file()):
return False
try:
content = legacy_path.read_text(encoding="utf-8-sig")
except (OSError, UnicodeDecodeError):
return False
marker_pairs = [(marker_start, marker_end)]
default_pair = (
IntegrationBase.CONTEXT_MARKER_START,
IntegrationBase.CONTEXT_MARKER_END,
)
if default_pair not in marker_pairs:
marker_pairs.append(default_pair)
start_idx = -1
end_idx = -1
has_start = False
has_end = False
for s, e in marker_pairs:
s_idx = content.find(s)
e_idx = content.find(e, s_idx if s_idx != -1 else 0)
has_s = s_idx != -1
has_e = e_idx != -1
if not has_s and not has_e:
continue
# Refuse to migrate a corrupted managed section: exactly one marker, or
# an end marker that does not follow the start.
if has_s != has_e or e_idx <= s_idx:
return False
marker_start, marker_end = s, e
start_idx, end_idx = s_idx, e_idx
has_start = True
has_end = True
break
if has_start and has_end:
removal_start = start_idx
removal_end = end_idx + len(marker_end)
if removal_end < len(content) and content[removal_end] == "\r":
removal_end += 1
if removal_end < len(content) and content[removal_end] == "\n":
removal_end += 1
if removal_start > 0 and content[removal_start - 1] == "\n":
if removal_start > 1 and content[removal_start - 2] == "\n":
removal_start -= 1
content = content[:removal_start] + content[removal_end:]
user_content = content.replace("\r\n", "\n").replace("\r", "\n").strip()
if not user_content:
legacy_path.unlink()
return True
try:
if target_path.is_file():
existing = target_path.read_text(encoding="utf-8-sig")
existing = existing.replace("\r\n", "\n").replace("\r", "\n")
if not existing.endswith("\n"):
existing += "\n"
new_content = existing + "\n" + user_content + "\n"
else:
new_content = user_content + "\n"
target_path.parent.mkdir(parents=True, exist_ok=True)
target_path.write_bytes(new_content.encode("utf-8"))
except (OSError, UnicodeDecodeError):
return False
legacy_path.unlink()
return True
def _migrate_legacy_kimi_dotted_skills(skills_dir: Path) -> tuple[int, int]:
"""Compatibility shim — migrate legacy dotted skill dirs in place.
.. deprecated::
Kept for direct callers/tests. New code should call
``_migrate_legacy_kimi_skills_dir`` directly.
Delegates to ``_migrate_legacy_kimi_skills_dir`` with *skills_dir* as both
source and destination, so it processes every ``speckit-*`` and
``speckit.*`` entry under *skills_dir*. Because the two paths are
identical, the same-path short-circuit there skips any directory whose
target resolves to itself; in practice this renames dotted
``speckit.xxx`` dirs to hyphenated ``speckit-xxx`` in place and never
moves content outside *skills_dir*.
Returns ``(migrated_count, removed_count)``.
"""
return _migrate_legacy_kimi_skills_dir(skills_dir, skills_dir)