feat(skill): 增加团队知识 CLI 引导

Author: sincerely90

README.md

@@ -122,7 +122,7 @@ Compound Engineering = 可选的执行 / 审查 / 测试消费方
 按需扩展：
 
 - 可选扩展：`aisee:design-spec`、`aisee:design-assets`、`aisee:svg-assets`、`aisee:image-object`、`aisee:spec-migrate`
-- 知识循环：`aisee:reflect`、`aisee:knowledge-curate`
+- 知识循环：`aisee:reflect`、`aisee:knowledge`、`aisee:knowledge-curate`
 - 硬件 / 实验域：`hw:srs`、`hw:architecture`、`hw:init`、`hw:change-plan`
 
 ## 功能特性
@@ -322,6 +322,7 @@ quick-fix / quick-research / 其它轻量 schema
 | `aisee:svg-assets` | 生成、矢量化、优化和校验 SVG assets。 |
 | `aisee:image-object` | 对象级图片分割、mask、去背景和导出工作流。 |
 | `aisee:reflect` | 沉淀可复用项目经验和工作流改进。 |
+| `aisee:knowledge` | 引导团队知识 CLI 的初始化、配置、同步、检索和 promote 流程。 |
 | `aisee:knowledge-curate` | 批量审查项目内 reusable knowledge candidates，产出可人工提交到 team knowledge 的 card drafts。 |
 
 硬件相关 skills 已保留，但仍在整合到 Aisee 主工作流中：
@@ -417,14 +418,22 @@ retrieval:
 常用命令：
 
 ```bash
+aisee knowledge init-repo --dest ../aisee-team-knowledge --initial-pack web-app --json
+aisee knowledge configure --path ../aisee-team-knowledge --enable-pack web-app --json
 aisee knowledge inspect --json
+aisee knowledge doctor --json
+aisee knowledge check --json
+aisee knowledge install --json
+aisee knowledge update --json
 aisee knowledge query --phase implementation --surface cli --query "public CLI JSON" --json
 aisee knowledge query --from-change <change> --for ce-work --json
 aisee context pack --change <change> --for ce-work --knowledge --json
+aisee knowledge promote-batch --curation <path> --team-path ../aisee-team-knowledge --pack web-app --json
 ```
 
 使用原则：
 
+- `aisee:knowledge` 负责引导这些 CLI 的日常使用，降低初始化、同步、检索和 promote 的门槛。
 - `install`、`update` 和 `promote-batch` 是实验性能力；本地默认 scaffold 不再由 PyPI CLI 提供。PR 自动化和 MCP 服务仍未稳定。
 - 通过 CLI 查询，不让 AI 直接扫描 `knowledge/cards/**/*.md`。
 - 只返回少量带边界的 matches，作为实现、review 或 verify 的提醒。

plugins/aisee-plugin/.codex-plugin/plugin.json

@@ -18,7 +18,7 @@
   "interface": {
     "displayName": "Aisee",
     "shortDescription": "AI-Enhanced Software Engineering for OpenSpec-driven development.",
-    "longDescription": "Aisee helps teams run OpenSpec-driven development with structured requirements, schema-aware change authoring, context packs, ID registry, and Compound Engineering handoffs.",
+    "longDescription": "Aisee helps teams run OpenSpec-driven development with structured requirements, schema-aware change authoring, context packs, team knowledge guardrails, and Compound Engineering handoffs.",
     "developerName": "Fengliang",
     "category": "Coding",
     "capabilities": [

plugins/aisee-plugin/references/knowledge-card-contract.md

@@ -24,6 +24,12 @@ CLI 的默认读取入口固定为：
 
 独立 team knowledge 仓库的默认初始化入口是 `aisee knowledge init-repo --dest <path> --initial-pack <id> --json`。marketplace-installed plugin 的 `skills/aisee-knowledge-curate/assets/team-knowledge/` 是 contract-valid 示例模板，也可以使用团队维护的外部模板仓库。配置完成后，用 `aisee knowledge configure --path <path> --enable-pack <id> --json` 写入项目 pin，再运行 `aisee knowledge doctor --json` 检查配置 path 与实际目录是否一致。需要预检该仓库能否被 `promote-batch` 写入时，可读取 `aisee knowledge check --team-path <path> --json` 返回中的 `team_knowledge.write_ready`。
 
+Skill 路由：
+
+- `aisee:knowledge`：引导团队知识 CLI 的初始化、配置、同步、检索和 promote 操作。
+- `aisee:knowledge-curate`：审查项目内候选知识，产出去敏、泛化、去重后的 curation report 和 card drafts。
+- `aisee:reflect`：在项目内生成可审查候选，不直接写入 team knowledge repo。
+
 读取顺序：
 
 1. 读取项目 `aisee/knowledge.yaml`，获得 repo/path/ref/packs/retrieval。

plugins/aisee-plugin/references/skill-taxonomy.md

@@ -32,6 +32,7 @@
 以下 skill 服务项目内复盘、审查和团队知识沉淀，不是每次迭代必经节点：
 
 - `aisee:reflect`
+- `aisee:knowledge`
 - `aisee:knowledge-curate`
 
 ## Hardware / Experimental

plugins/aisee-plugin/skills/aisee-knowledge/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: aisee:knowledge
+description: 引导团队知识 CLI 的日常使用。用于用户询问团队知识是否可用、如何初始化或接入 team knowledge、如何同步知识仓库、如何查询 guardrails、如何把已审查 drafts 写入 team knowledge，或提到 aisee knowledge、knowledge.yaml、team knowledge、团队知识命令时触发。它负责选择和执行 `aisee knowledge` 命令；候选知识审查和 card draft 生成仍转交 `aisee:knowledge-curate`。
+---
+
+# aisee:knowledge
+
+引导团队知识 CLI 的低门槛使用：初始化、配置、检查、同步、检索和已审查 drafts 的写入。
+
+## 职责
+
+- 检查业务项目是否已配置 `aisee/knowledge.yaml`。
+- 使用 `aisee knowledge inspect/doctor/check` 判断 team knowledge 状态。
+- 使用 `init-repo` 和 `configure` 建立最小可用团队知识链路。
+- 使用 `install/update` 同步已 pin 的 Git team knowledge checkout。
+- 使用 `query` 或 `context pack --knowledge` 给实现、审查和验证提供少量 guardrails。
+- 在用户明确授权后，使用 `promote-batch` 把已审查 curation report 写入本地 team knowledge worktree。
+
+## 不负责
+
+- 不审查、去敏、泛化项目候选知识；这属于 `aisee:knowledge-curate`。
+- 不从聊天记录或全仓库 Markdown 临时生成 active team card。
+- 不让 team knowledge 替代 OpenSpec specs、tasks、contracts、source-map 或 baseline。
+- 不把 `aisee/cache/knowledge-index.json` 当事实源。
+- 不自动创建分支、commit、push、merge 或 PR。
+
+## Workflow
+
+按用户目标选择模式；需要命令细节时读取 `references/workflow.md`。
+
+| 用户目标 | 处理方式 |
+|---|---|
+| “检查团队知识是否可用” | 运行 `aisee knowledge inspect --json`、`doctor --json`，必要时 `check --json`。 |
+| “初始化团队知识库” | 先说明写入路径，用户确认后运行 `init-repo`，再 `configure`。 |
+| “配置当前项目使用团队知识” | 运行 `configure --path <path> --enable-pack <pack>`，再 `doctor`。 |
+| “同步团队知识” | 检查 `knowledge.yaml` 后运行 `install` 或 `update`。 |
+| “查询可复用经验” | 运行 `query`；有明确 change 时优先 `query --from-change <change> --for ce-work`。 |
+| “实现时带团队知识” | 使用 `aisee context pack --change <change> --for ce-work --knowledge --json`。 |
+| “把候选沉淀到团队知识” | 若还没有审查报告，转交 `aisee:knowledge-curate`；已有 report 且用户授权后使用 `promote-batch`。 |
+
+## Guardrails
+
+- 写入 `aisee/knowledge.yaml`、team knowledge repo 或 cache 前，说明将写入的路径和命令。
+- `promote-batch` 前必须确认目标路径是 team knowledge worktree，并优先运行 `aisee knowledge check --team-path <path> --json`。
+- `promote-batch` 默认写入 candidate；只有用户明确要求激活时才传 `--activate`。
+- `install/update` 只处理已配置的 Git checkout；dirty checkout 被阻断时不要自动清理。
+- 最终回复说明运行过的命令、状态、写入路径、命中 card 数量和剩余风险。

plugins/aisee-plugin/skills/aisee-knowledge/evals/evals.json

@@ -0,0 +1,88 @@
+{
+  "schema_version": "aisee.skill-eval.v1",
+  "skill_name": "aisee:knowledge",
+  "harness": {
+    "type": "skill-eval",
+    "owner": "aisee",
+    "fact_source_policy": "eval cases are test inputs, not runtime facts"
+  },
+  "evals": [
+    {
+      "id": "knowledge-001",
+      "name": "guide-team-knowledge-onboarding",
+      "scenario": "team-knowledge-onboarding",
+      "prompt": "帮我把当前项目接入团队知识库，并检查以后实现时能不能检索 guardrails。",
+      "context": {
+        "files": [],
+        "assumptions": [
+          "用户要求接入和验证团队知识 CLI。"
+        ]
+      },
+      "expected_output": "应先检查或创建 team knowledge repo，再用 configure 写入项目 pin，并通过 doctor/check/query 验证；不得手工发明 knowledge.yaml 或把知识库当 OpenSpec 事实源。",
+      "expected_outputs": [
+        "使用 aisee knowledge init-repo 或 configure。",
+        "运行 doctor/check 验证配置。",
+        "说明 query 或 context pack --knowledge 的使用方式。"
+      ],
+      "must_ask": [
+        "如果需要写入新路径，应确认目标 team knowledge 路径。"
+      ],
+      "must_include": [
+        "aisee knowledge configure",
+        "aisee knowledge doctor",
+        "aisee knowledge query"
+      ],
+      "must_not": [
+        "不得直接递归扫描 knowledge/cards 当作默认流程。",
+        "不得把 team knowledge 当作 OpenSpec baseline 或 current change 事实源。"
+      ],
+      "quality_checks": [
+        "区分配置、同步、检索和写入流程。",
+        "写入前说明路径和命令。"
+      ],
+      "fact_source_constraints": [
+        "team knowledge 是 guardrail retrieval，不替代 OpenSpec、source-map、tasks 或 contracts。"
+      ],
+      "files": []
+    },
+    {
+      "id": "knowledge-002",
+      "name": "route-curation-to-knowledge-curate",
+      "scenario": "team-knowledge-promotion",
+      "prompt": "把这次项目经验沉淀到团队知识里，如果可以就写入 team repo。",
+      "context": {
+        "files": [],
+        "assumptions": [
+          "用户提出沉淀到团队知识，但未说明已有 curation report。"
+        ]
+      },
+      "expected_output": "应先转交或建议使用 aisee:knowledge-curate 生成去敏、泛化、去重后的 batch report；只有已有 report 且用户明确授权目标路径时才运行 promote-batch。",
+      "expected_outputs": [
+        "说明 aisee:knowledge-curate 负责生成 drafts。",
+        "说明 promote-batch 只写本地 worktree。",
+        "提醒默认 candidate，明确授权后才可 --activate。"
+      ],
+      "must_ask": [
+        "确认是否已有 curation report。",
+        "确认 team knowledge worktree 路径和是否允许写入。"
+      ],
+      "must_include": [
+        "aisee:knowledge-curate",
+        "aisee knowledge check --team-path",
+        "aisee knowledge promote-batch"
+      ],
+      "must_not": [
+        "不得直接从聊天记录生成 active card 并写入 team repo。",
+        "不得自动 commit、push、merge 或创建 PR。"
+      ],
+      "quality_checks": [
+        "保持 knowledge 和 knowledge-curate 职责分离。",
+        "强调用户授权和 write_ready 检查。"
+      ],
+      "fact_source_constraints": [
+        "curation report 是待审材料；active team card 才是默认检索对象。"
+      ],
+      "files": []
+    }
+  ]
+}

plugins/aisee-plugin/skills/aisee-knowledge/references/workflow.md

@@ -0,0 +1,114 @@
+# Team Knowledge CLI Workflow
+
+## 1. Inspect
+
+检查当前项目是否已接入团队知识：
+
+```bash
+aisee knowledge inspect --json
+aisee knowledge doctor --json
+aisee knowledge check --json
+```
+
+使用原则：
+
+- `inspect` 看配置、packs 和 cards。
+- `doctor` 看 `aisee/knowledge.yaml` 与本地路径是否一致。
+- `check` 校验 pack/card，并返回 `team_knowledge.write_ready`。
+
+## 2. Initialize And Configure
+
+新建独立 team knowledge 仓库骨架：
+
+```bash
+aisee knowledge init-repo --dest <team-knowledge> --initial-pack web-app --json
+aisee knowledge check --team-path <team-knowledge> --json
+aisee knowledge configure --path <team-knowledge> --enable-pack web-app --json
+aisee knowledge doctor --json
+```
+
+如果团队已有外部 Git 仓库，业务项目只 pin repo/ref/path：
+
+```bash
+aisee knowledge configure \
+  --path .aisee/team-knowledge \
+  --repo <git-url> \
+  --ref <branch-or-tag> \
+  --enable-pack web-app \
+  --json
+```
+
+随后运行 `install` clone 到配置路径。
+
+## 3. Sync
+
+同步已配置的 Git team knowledge checkout：
+
+```bash
+aisee knowledge install --json
+aisee knowledge update --json
+```
+
+边界：
+
+- `install` 只 clone `aisee/knowledge.yaml` 中声明的 repo/path/ref。
+- `update` 会拒绝 dirty checkout，除非用户明确选择 `--allow-dirty`。
+- 失败时报告 issue code，不自动删除用户已有 worktree。
+
+## 4. Query
+
+直接按场景检索：
+
+```bash
+aisee knowledge query --phase implementation --surface cli --query "public CLI JSON" --json
+```
+
+基于当前 OpenSpec change 检索：
+
+```bash
+aisee knowledge query --from-change <change> --for ce-work --json
+```
+
+给执行上下文注入少量 guardrails：
+
+```bash
+aisee context pack --change <change> --for ce-work --knowledge --json
+```
+
+读取结果时看：
+
+- `knowledge.matches`：可使用的 active cards。
+- `knowledge.explain`：被过滤原因，如 `status is candidate`。
+- `config.retrieval.max_cards`：默认返回数量上限。
+
+## 5. Index
+
+索引只是可删除 cache，不是事实源：
+
+```bash
+aisee knowledge index --json
+aisee knowledge index --team-path <team-knowledge> --json
+```
+
+项目侧 cache 默认写入 `aisee/cache/knowledge-index.json`；team repo cache 默认写入 `indexes/lexical-index.json`。
+
+## 6. Promote Reviewed Drafts
+
+如果用户还没有 curation report，先转交 `aisee:knowledge-curate` 生成审查报告和 card drafts。
+
+已有 curation report 且用户明确授权写入本地 team knowledge worktree 后：
+
+```bash
+aisee knowledge check --team-path <team-knowledge> --json
+aisee knowledge promote-batch \
+  --curation <report> \
+  --team-path <team-knowledge> \
+  --pack web-app \
+  --json
+```
+
+激活规则：
+
+- 默认不传 `--activate`，写入 `candidate`。
+- 只有用户明确说“激活 / active / 直接启用”时才传 `--activate`。
+- `promote-batch` 不会 commit、push 或创建 PR。