Skip to content

feat: unify .agents full architecture and v3 beta migration#2

Closed
MisonL wants to merge 27 commits intomainfrom
preview/agents-v3
Closed

feat: unify .agents full architecture and v3 beta migration#2
MisonL wants to merge 27 commits intomainfrom
preview/agents-v3

Conversation

@MisonL
Copy link
Copy Markdown
Owner

@MisonL MisonL commented Mar 4, 2026

背景

本 PR 实现统一 full 目录体系:项目只维护 .agents(Canonical),并自动生成 .agent / .gemini 兼容投影;同时完成 legacy 迁移与 beta 预发布配套。

规划对齐矩阵(v3 Full)

  • 1. 受管证据识别收敛:仅认 .agents/manifest.json、托管 .codex manifest、.agent/.ag-kit-projection.json.gemini/.ag-kit-projection.json.gemini/agents/ag-kit-*.md
  • 2. 消除误判:非受管 .agent/.gemini 与仅存在空 .agents 不再判定为 installed。
  • 3. 一次性自动迁移:init/update/update-all/doctor --fix 首轮触发,状态文件 ~/.ag-kit/migrations/v3.json(支持 AG_KIT_MIGRATION_STATE_PATH)。
  • 4. 自动迁移幂等:已迁移工作区不重复迁移;失败项不中断整体,成功项照常落状态。
  • 5. CLI 参数对齐:ag-kit update 正式支持 --non-interactive
  • 6. 状态输出对齐:ag-kit status 补充 Auto-Migration(v3): done|pending
  • 7. 仓库单源收敛:内置模板仅 .agents/**;发布白名单移除 .agent/**
  • 8. Context7 主备约定:context7 + context7_backup,并约定主失败再备;示例配置移除 values
  • 9. 文档一致性:READMEdocs/migration-v3-beta.mddocs/operations.md 同步 CLI 真实行为。
  • 10. 验收通过:bun run testbun run health-check 全通过。

核心改动

  1. CLI 统一 full 语义
  • ag-kit init/update 默认 full。
  • --target gemini|codex 保留兼容,但内部归一为 full。
  • 冲突交互仅在真实“非托管冲突”时触发,托管投影不再重复询问。
  1. 适配器与迁移
  • CodexAdapter 升级为 full 主适配器:
    • .agents 原子更新 + manifest v3。
    • .agent / .gemini 投影同步。
    • 仅清理托管 legacy .codex;非托管 .codex 保留。
  • 新增受管证据模块:统一判定 canonical/projection/legacy 信号。
  1. MCP
  • 同步 Context7 主备:context7 + context7_backup
  • .gemini/settings.json 采用合并策略,保留用户非托管字段。
  1. 文档与版本
  • 新增迁移手册:docs/migration-v3-beta.md
  • 更新 README.mddocs/operations.mddocs/multi-target-adapter.mddocs/mapping-spec.md
  • 版本提升为 3.0.0-beta.0

验证

已执行并通过:

bun run test
bun run health-check
npm pack --dry-run

发布状态

  • npm beta 已发布:@mison/ag-kit-cn@3.0.0-beta.0
  • GitHub prerelease:v3.0.0-beta.0

MisonL added 27 commits March 4, 2026 12:04
@MisonL MisonL closed this Mar 11, 2026
@MisonL MisonL deleted the preview/agents-v3 branch March 11, 2026 01:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant