diff --git a/.blueprint/manifest.yaml b/.blueprint/manifest.yaml index 6a50064..a5148af 100644 --- a/.blueprint/manifest.yaml +++ b/.blueprint/manifest.yaml @@ -1,9 +1,9 @@ version: 1 name: 炼境 description: > - Git 多空间开发管理器。以蓝图为神经系统，以 Claude 为智能层， - 持续感知所管理项目的功能运转、质量状态与成长方向， - 成为每个项目的贴身导师。炼境本身亦被纳入其中， + Git 多空间开发管理器与项目 Agent 化的本地控制面。以蓝图为神经系统， + 为 Codex、Claude 等可替换客户端 adapter 分发基线、发现状态并采集交付信号； + 项目自身保留业务规则、测试、部署声明与交付决策。炼境本身亦被纳入其中， 形成可自我进化的开发智能闭环。 iteration: 1 updated: 2026-09-21 @@ -463,9 +463,10 @@ modules: - id: agent-client-capability-packs name: Agent 客户端能力包 area: infra - status: in_progress - progress: 0 - note: "P2：以工具无关项目上下文为锚点，收敛 Codex / Claude 客户端差异；不复制 MCP、凭证或部署能力。" + status: done + progress: 100 + note: "P2 完成：工具无关 canonical context、版本化能力包自检与 Codex Skill-only 投影已闭环；不复制 MCP、凭证或部署能力。" + updated: 2026-09-21 position: [2250, 800] edges: # 前端依赖 diff --git a/.blueprint/modules/agent-client-capability-packs.md b/.blueprint/modules/agent-client-capability-packs.md index b543e76..90cdd7c 100644 --- a/.blueprint/modules/agent-client-capability-packs.md +++ b/.blueprint/modules/agent-client-capability-packs.md @@ -1,8 +1,8 @@ --- id: agent-client-capability-packs name: Agent 客户端能力包 -status: planned -progress: 0 +status: done +progress: 100 --- ## 概述 @@ -41,16 +41,18 @@ Codex 用户级插件 - acceptance: "[cargo test] verify_onboarding(project_id) → 对 canonical 缺失、legacy-only、pack 版本不符、Codex MCP 不可用分别返回可区分的 ready/missing/legacy/version_mismatch/unavailable 信号，且不将任一状态伪报为 ready。" - done_note: "2026-09-21：新增 `.lian-jing/capability-packs.json` 基线描述符；verify_onboarding 对项目上下文、能力包、Codex skill/MCP 和既有基线逐项返回结构化状态与可执行升级提示。" -### 🔵 P2-C. Codex Skill-only 可移植能力包 -- status: in_progress +### ✅ P2-C. Codex Skill-only 可移植能力包 +- status: done - complexity: M - depends: P2-B. 能力包描述符与 onboarding 自检报告 - files: plugins/lian-jing-codex/plugin.json, plugins/lian-jing-codex/.codex-plugin/plugin.json, plugins/lian-jing-codex/skills/lian-jing/SKILL.md, plugins/README.md - acceptance: "[插件结构检查] manifest 与 skill 路径均在插件根目录内，skill 不含 project_id、127.0.0.1 MCP URL、凭证或部署命令；[新 Codex 会话] 已接入项目可按 skill 调用既有 MCP，未接入项目输出接入诊断而非虚构状态。" +- done_note: "2026-09-21：个人本地 marketplace 安装后，新 Codex 会话确认 Skill 已加载；未接入项目如实报告 canonical context 与 MCP 缺失，未猜测 project_id、凭证或交付状态。" -### 📋 P2-D. 接入包版本、升级说明与架构防腐同步 -- status: todo +### ✅ P2-D. 接入包版本、升级说明与架构防腐同步 +- status: done - complexity: M - depends: P2-B. 能力包描述符与 onboarding 自检报告, P2-C. Codex Skill-only 可移植能力包 - files: AGENTS.md, docs/ai-context/project-brief.md, docs/ai-context/project-context.yaml, docs/templates/agents-meta-rules.md, resources/onboarding/ - acceptance: "[cargo test] 接入包升级检查 → 旧 context/旧能力包给出明确 upgrade_hint 且不自动覆盖用户配置；[rg] 常驻架构文档将炼境描述为项目控制面、客户端描述为 adapter，且不把客户端插件表述为凭证或部署所有者。" +- done_note: "2026-09-21：base-onboarding 升至 v1.1.0；旧能力包会显式返回 version_mismatch 与升级提示。托管模板、Git 工作流与常驻架构文档统一为 canonical context / 控制面 / 客户端 adapter 边界。" diff --git a/AGENTS.md b/AGENTS.md index 9b9b171..0506224 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,15 +4,15 @@ ## 项目定位 -Git 多空间开发管理器，同时也是**项目 Agent 化改造引擎**。 -以蓝图为神经系统，以 Claude 为智能层，感知所管理项目的功能运转、质量状态与成长方向。 +Git 多空间开发管理器，同时也是**项目 Agent 化的本地控制面**。 +以蓝图为神经系统，为 Codex、Claude 等可替换客户端 adapter 分发基线、发现状态并采集交付信号；项目自身保留业务规则、测试、部署声明与交付决策。 炼境本身亦被纳入其中，形成可自我进化的开发智能闭环。 ## 技术栈 - 前端：React 19 + TypeScript + TailwindCSS + React Query + Zustand + React Flow - 后端：Rust + Tauri v2 + SQLite（rusqlite + r2d2） -- MCP Server：内嵌于 Tauri 进程（HTTP），供 Claude Code 调用炼境数据 +- MCP Server：内嵌于 Tauri 进程（HTTP），供 Codex、Claude 等客户端 adapter 调用炼境数据 - 包管理：pnpm（禁止 npm/yarn/npx/bun） ## 炼境特有开发约束 @@ -30,7 +30,7 @@ src-tauri/src/db.rs SQLite 建表 + migration 逻辑 src-tauri/src/mcp_server.rs MCP Server 路由层 + SSE 协议（agent 调用炼境的入口） src-tauri/src/mcp_tools.rs MCP 工具 schema + dispatch + 实现（工具清单以 tools_list_result 为准） src-tauri/src/mcp_webhook.rs Gitea webhook 处理（push/PR 事件写入飞轮） -src-tauri/src/mcp_inject.rs MCP 配置注入（写入被管理项目的 .codex/config.toml 与 Claude 兼容配置） +src-tauri/src/mcp_inject.rs 接入注入（写入 canonical `.lian-jing/context.json`、`.codex/config.toml` 与 Claude 兼容配置） src-tauri/resources/onboarding/ 接入包分发模板（AGENTS.md/lefthook/git-workflow） .blueprint/ 项目蓝图（manifest + 模块详情 + 任务卡） docs/ai-context/ AI 上下文文档（速查卡、契约映射） diff --git a/docs/ai-context/git-workflow.md b/docs/ai-context/git-workflow.md index d22abce..307a774 100644 --- a/docs/ai-context/git-workflow.md +++ b/docs/ai-context/git-workflow.md @@ -3,7 +3,7 @@ > 把此文件粘贴给任何 AI Agent，让它了解本项目的 git 工作方式。由炼境接入包分发。 > `ONBOARDING_MANAGED` 标记块由炼境版本化管理（重跑接入包可原位升级），块外可自由补充项目特有约定。 - + > ⚠️ 本块由炼境版本化托管，升级时**整块原位覆盖**——项目定制请写到块外，块内手改必丢。 ## 分支策略（复杂度感知） @@ -78,13 +78,13 @@ PR 别攒太大（建议每 3~5 个 commit 或几百行内就开一次），否 ## PR 创建（炼境托管项目） -本项目由炼境管理，MCP 已注入且 `.claude/liangjing.json` 含 `project_id`。 +本项目由炼境管理；`.lian-jing/context.json` 是 `project_id` 的唯一来源。Codex 使用项目级 `.codex/config.toml` 发现 MCP（项目须受信任）；`.claude/liangjing.json` 仅是旧项目的 Claude 兼容投影。 炼境 MCP 是单一全局服务器 `lian-jing`，所有工具显式传 `project_id` 寻址，无需 group_id。 **推送分支后，通过炼境 MCP 创建 PR，禁止用 curl + git credential fill 提取 token：** ``` -1. Read .claude/liangjing.json → 取出 project_id +1. Read .lian-jing/context.json → 取出 project_id 2. 调用 MCP 工具 create_pull_request： { "project_id": "", "head": "feat/", "base": "main", "title": "", "body": "<变更摘要>" } @@ -93,6 +93,8 @@ PR 别攒太大（建议每 3~5 个 commit 或几百行内就开一次），否 若炼境未运行（MCP 不可用），降级方案：去 Gitea 网页手动创建 PR。 +> 若只存在 `.claude/liangjing.json`，先调用 `inject_mcp(project_id)` 迁移到 canonical context；禁止将 Codex 用户级插件、客户端项目 UI 或全局配置当作项目身份来源。 + ## 交付状态（炼境托管项目） 在准备开 PR、合并 PR 或排查部署问题时，先调用 MCP 工具： diff --git a/docs/ai-context/project-brief.md b/docs/ai-context/project-brief.md index 5bc993c..a3f6709 100644 --- a/docs/ai-context/project-brief.md +++ b/docs/ai-context/project-brief.md @@ -1,6 +1,6 @@ # 炼境 — 速查卡 -**定位**：Git 多空间开发管理器 + 项目 Agent 化改造引擎。Tauri v2 桌面 App，管理多个开发项目，为每个项目注入 Agent 友好基础设施，形成智能成长飞轮。 +**定位**：项目 Agent 化的本地控制面。炼境管理多个 Git 工作区，分发版本化基线、发现状态并汇总交付信号；项目本身仍拥有业务规则、测试、部署声明与交付决策。 ## 技术栈 @@ -9,7 +9,7 @@ | 前端 | React 19 + TypeScript + TailwindCSS + React Query + Zustand + React Flow | | 后端 | Rust + Tauri v2 | | 数据 | SQLite（rusqlite + r2d2） | -| MCP | 内嵌 HTTP Server（供 Claude Code、Codex 等客户端调用） | +| MCP | 内嵌 HTTP Server（供 Codex、Claude 等客户端 adapter 调用） | | 包管理 | pnpm | ## 关键约定（改代码前必看） @@ -18,7 +18,7 @@ 2. **DB 变更必须有 migration**：在 `src-tauri/src/db.rs` 的 `migrate()` 里补语句，否则旧版本升级报错 3. **Rust 业务函数依赖注入**：禁止内部 `pool().get()`，连接由调用方传入 4. **接入包模板 = 分发给被管理项目的规则**：改 `resources/onboarding/` 务必同步 `docs/templates/` -5. **项目身份上下文**：`.lian-jing/context.json` 是工具无关的 `project_id` 单一事实来源；`.claude/liangjing.json` 仅保留为 Claude 兼容投影 +5. **项目身份上下文**：`.lian-jing/context.json` 是工具无关的 `project_id` 单一事实来源；`.claude/liangjing.json` 仅保留为 Claude 兼容投影；`.lian-jing/capability-packs.json` 记录托管基线版本，版本不符必须通过自检报告升级提示 ## 目录速查 diff --git a/docs/ai-context/project-context.yaml b/docs/ai-context/project-context.yaml index febf87a..94d9926 100644 --- a/docs/ai-context/project-context.yaml +++ b/docs/ai-context/project-context.yaml @@ -22,7 +22,7 @@ contracts: - ".lian-jing/context.json" - ".lian-jing/capability-packs.json" - ".claude/liangjing.json" - doc: "`.lian-jing/context.json` 是 project_id 的工具无关单一事实来源；`.claude/liangjing.json` 仅为兼容投影；`.lian-jing/capability-packs.json` 是炼境分发基线的版本描述。迁移必须保留未知字段，验证必须返回显式状态，且不得以客户端全局配置或项目 UI 身份替代项目根目录上下文。" + doc: "`.lian-jing/context.json` 是 project_id 的工具无关单一事实来源；`.claude/liangjing.json` 仅为兼容投影；`.lian-jing/capability-packs.json` 是炼境分发基线的版本描述。迁移必须保留未知字段；验证必须返回显式状态与 upgrade_hint；升级仅覆盖炼境托管文件，绝不覆盖项目定制或手工 MCP 配置，且不得以客户端全局配置或项目 UI 身份替代项目根目录上下文。" - label: Tauri command 接口（前后端契约） paths: diff --git a/docs/templates/agents-meta-rules.md b/docs/templates/agents-meta-rules.md index 98ff688..dafbbbb 100644 --- a/docs/templates/agents-meta-rules.md +++ b/docs/templates/agents-meta-rules.md @@ -1,6 +1,6 @@ --- -version: 1.1.0 -updated: 2026-07-03 +version: 1.2.0 +updated: 2026-09-21 usage: 炼境接入包分发时写入被管理项目 AGENTS.md 的元规则标准内容 --- @@ -9,6 +9,12 @@ usage: 炼境接入包分发时写入被管理项目 AGENTS.md 的元规则标 > 本节由炼境接入包分发，规则技术栈无关，适用于所有项目和所有 AI 工具。 > 项目特定的路径映射见 `docs/ai-context/project-context.yaml`。 +## 炼境项目上下文与能力包 + +- 项目根目录 `.lian-jing/context.json` 是工具无关的 `project_id` 单一事实来源；客户端项目 UI、用户级插件和全局配置都不能替代它。 +- `.claude/liangjing.json` 仅用于兼容已接入的旧 Claude 项目；发现 legacy-only 状态时，应通过炼境迁移，不应复制或猜测 ID。 +- `.lian-jing/capability-packs.json` 仅描述炼境托管基线的版本与自检。升级必须显式报告版本不符，并且不能覆盖项目自己的业务规则、测试、部署声明或手工 MCP 配置。 + --- ## Agent 友好工程四支柱 diff --git a/src-tauri/resources/onboarding/.lian-jing/capability-packs.json b/src-tauri/resources/onboarding/.lian-jing/capability-packs.json index 27d4bb1..eb3d3bf 100644 --- a/src-tauri/resources/onboarding/.lian-jing/capability-packs.json +++ b/src-tauri/resources/onboarding/.lian-jing/capability-packs.json @@ -3,7 +3,7 @@ "packs": [ { "pack_id": "base-onboarding", - "version": "1.0.0", + "version": "1.1.0", "supported_clients": ["codex", "claude"], "project_artifacts": [ "AGENTS.md", @@ -11,7 +11,7 @@ ".lian-jing/context.json" ], "self_check": "verify_onboarding", - "upgrade_hint": "调用 apply_onboarding_pack(project_id) 更新基线；项目身份上下文由 inject_mcp(project_id) 创建或迁移。" + "upgrade_hint": "调用 apply_onboarding_pack(project_id) 更新版本化基线；项目身份上下文由 inject_mcp(project_id) 创建或迁移。该升级仅覆盖炼境托管的接入包文件，不覆盖项目定制或手工 MCP 配置。" } ] } diff --git a/src-tauri/resources/onboarding/AGENTS.md.tmpl b/src-tauri/resources/onboarding/AGENTS.md.tmpl index 922b72c..4b7a263 100644 --- a/src-tauri/resources/onboarding/AGENTS.md.tmpl +++ b/src-tauri/resources/onboarding/AGENTS.md.tmpl @@ -18,7 +18,7 @@ - + > ⚠️ 本块由炼境版本化托管，升级时**整块原位覆盖**——项目定制请写到块外，块内手改必丢（2026-07-15 炼境自身实锤丢失 5 段定制后新增本警示）。 ## 核心开发约束 @@ -66,6 +66,13 @@ 见 `docs/ai-context/git-workflow.md`（分支策略 + Conventional Commits + Rules-Applied trailer + PR 规范）。 **commit 必须符合 Conventional Commits**（lefthook 强制），炼境据此采集飞轮数据。 +## 炼境项目上下文与能力包 + +- `.lian-jing/context.json` 是项目 `project_id` 的工具无关单一事实来源；不要从客户端项目 UI、用户级插件或全局配置推断项目身份。 +- `.claude/liangjing.json` 只是旧项目的 Claude 兼容投影。只发现它时，调用 `inject_mcp(project_id)` 迁移，而不是手工复制或猜测 ID。 +- `.lian-jing/capability-packs.json` 记录炼境托管基线的版本。`verify_onboarding(project_id)` 报告 `legacy`、`version_mismatch` 等状态时，按其 `detail` 中的升级提示处理。 +- `apply_onboarding_pack(project_id)` 只更新炼境明确托管的接入包文件；项目自己的业务规则、测试、部署声明和手工定义的同名 MCP server 仍归项目所有，不能被升级覆盖。 + ## agent 按钮与验证路径 功能的本体是代码层的能力；UI 按钮是它给人的投影，**agent 按钮**是给 agent 的投影 diff --git a/src-tauri/resources/onboarding/git-workflow.md.tmpl b/src-tauri/resources/onboarding/git-workflow.md.tmpl index 8bc5627..307a774 100644 --- a/src-tauri/resources/onboarding/git-workflow.md.tmpl +++ b/src-tauri/resources/onboarding/git-workflow.md.tmpl @@ -3,7 +3,7 @@ > 把此文件粘贴给任何 AI Agent，让它了解本项目的 git 工作方式。由炼境接入包分发。 > `ONBOARDING_MANAGED` 标记块由炼境版本化管理（重跑接入包可原位升级），块外可自由补充项目特有约定。 - + > ⚠️ 本块由炼境版本化托管，升级时**整块原位覆盖**——项目定制请写到块外，块内手改必丢。 ## 分支策略（复杂度感知） @@ -78,13 +78,13 @@ PR 别攒太大（建议每 3~5 个 commit 或几百行内就开一次），否 ## PR 创建（炼境托管项目） -本项目由炼境管理；Codex 使用项目级 `.codex/config.toml` 发现 MCP（项目须受信任），`.claude/liangjing.json` 含 `project_id`。 +本项目由炼境管理；`.lian-jing/context.json` 是 `project_id` 的唯一来源。Codex 使用项目级 `.codex/config.toml` 发现 MCP（项目须受信任）；`.claude/liangjing.json` 仅是旧项目的 Claude 兼容投影。 炼境 MCP 是单一全局服务器 `lian-jing`，所有工具显式传 `project_id` 寻址，无需 group_id。 **推送分支后，通过炼境 MCP 创建 PR，禁止用 curl + git credential fill 提取 token：** ``` -1. Read .claude/liangjing.json → 取出 project_id +1. Read .lian-jing/context.json → 取出 project_id 2. 调用 MCP 工具 create_pull_request： { "project_id": "", "head": "feat/", "base": "main", "title": "", "body": "<变更摘要>" } @@ -93,6 +93,8 @@ PR 别攒太大（建议每 3~5 个 commit 或几百行内就开一次），否 若炼境未运行（MCP 不可用），降级方案：去 Gitea 网页手动创建 PR。 +> 若只存在 `.claude/liangjing.json`，先调用 `inject_mcp(project_id)` 迁移到 canonical context；禁止将 Codex 用户级插件、客户端项目 UI 或全局配置当作项目身份来源。 + ## 交付状态（炼境托管项目） 在准备开 PR、合并 PR 或排查部署问题时，先调用 MCP 工具： diff --git a/src-tauri/src/commands/onboarding.rs b/src-tauri/src/commands/onboarding.rs index 5f02f9a..4a6704a 100644 --- a/src-tauri/src/commands/onboarding.rs +++ b/src-tauri/src/commands/onboarding.rs @@ -25,7 +25,7 @@ const TMPL_CAPABILITY_PACKS: &str = include_str!("../../resources/onboarding/.lian-jing/capability-packs.json"); const PROJECT_CONTEXT_SCHEMA_VERSION: u64 = 1; const CAPABILITY_PACK_SCHEMA_VERSION: u64 = 1; -const BASE_ONBOARDING_PACK_VERSION: &str = "1.0.0"; +const BASE_ONBOARDING_PACK_VERSION: &str = "1.1.0"; /// 单个模板的分发结果。 #[derive(Debug, Serialize, Deserialize, Clone, PartialEq, Eq)] @@ -999,6 +999,12 @@ mod tests { assert_eq!(pack_ready.state, VerifyState::Ready); let pack_old = check_capability_packs(Some(r#"{"schema_version":0,"packs":[]}"#)); assert_eq!(pack_old.state, VerifyState::VersionMismatch); + + let outdated_pack = check_capability_packs(Some( + r#"{"schema_version":1,"packs":[{"pack_id":"base-onboarding","version":"1.0.0"}]}"#, + )); + assert_eq!(outdated_pack.state, VerifyState::VersionMismatch); + assert!(outdated_pack.detail.contains("重跑接入包可升级")); } #[test]