@michelj/context-guard 0.4.3 → 0.6.1

package/README.zh-CN.md

@@ -1,302 +1,167 @@
-# Context Guard Skill
+[官网与交互演示](https://michel-johnson.github.io/Context-Guard-Skill/?lang=zh)
 
-语言：[English](README.md) | **中文**
+# Context Guard
 
-Context Guard 是一个给 Codex 用的项目记忆 skill。它把任务主线、支线、bad case 和验证链路保存在项目自己的 `.codex/context/` 里，让 Codex 在不同 session 之间也能知道“现在做到哪里、踩过哪些坑、下次怎么检查”。
-
-## 能做什么
-
-- **维护项目 context**：自动创建并更新 `.codex/context/`。
-- **保留用户原话**：把短用户指令、约束、偏好、路线提示和 bad case 反馈写入 `user-messages.md`。
-- **敏感信息只留本地**：公开 context 里只保留脱敏指针，真正需要复用的凭据只放在 `.codex/context/private/`。
-- **记录路线图**：维护主线、支线、分叉节点和当前进度。
-- **记录 bad case**：保存问题现象、触发条件、原因、修复方式和防复发检查。
-- **生成 Roadmap HTML**：支持卡片和高密度紧凑总览，点击节点看详情。
-- **区分人类视图和 agent 视图**：HTML 给人看，Markdown/JSON 给 Codex 读取。
-- **支持多语言记录**：按项目偏好用中文或英文写 context。
-- **处理任务切换**：遇到新方向、支线任务或中断任务时，帮助 Codex park/resume。
-- **绑定 Subagent 项目**：把 agent ID 绑定到实际本地项目根目录，避免 context 写回父工作区或 SSH 服务器。
-- **沉淀真实修复**：优先保存 Subagent 实际发现的问题、根因、修复和验证；重复完成事件不会重复建节点。
-- **测试由人类设计**：Codex 只复用已确认检查，或提出草案等待用户确认，不静默创建长期测试。
-- **用功能链覆盖 bad case**：优先把多个 bad case 挂到同一条真实功能/工作流测试链上，而不是为每个 bad case 单独造测试。
-- **默认运行已确认测试**：用户创建或确认的测试，默认每次开发结束都要运行；只有用户说明不必每次运行时才降频。
-- **提供测试中台入口**：`dev-complete` 会统一运行已确认的 always-run 测试，成功清理临时产物，失败保留证据。
+语言：[English](README.md) | **中文**
 
-## 安装
+**下一代人与编码 Agent 的协作层。**
 
-使用 npx 安装：
+多数工具仍把 *对话* 当成工作场所。线程即记忆、即审批面、即项目。对话一结束，下一个 Agent 从零开始。聊天里的一句「好」既不是授权，也不是发布，更不是可复用的记录。
 
-```bash
-npx @michelj/context-guard install
-```
+Context Guard 把 **项目** 当成工作场所：
 
-也可以全局安装，让 npm 包自动把 skill 复制到 Codex 的 skill 目录：
+1. **一张共享 Map** — 模块、职责、Bug、待办和验证落在同一份耐久结构上。现行存储法是 [`fs-v2`](references/design-current.md)。
+2. **隔离的 Session** — 每次执行写自己的 Session。对话不是 Main。用户把 Coordinator 挂到节点上时，挂载不写入 Main。执行 Session 要等该事项的 brief 获批后才创建。
+3. **人只跟 Coordinator 说话** — Cloud Coordinator、本地工作台 Coordinator，或 Codex Session 当 Coordinator。确认和「去做」发生在那里。干活的 Session 不对人说。灰卡切片是以后的事，不是当前默认。
+4. **发布进 Main** — 人审核过的工作才进已提交的 main 基线。Session 草稿仍是草稿，直到过门禁。人可以直接改 Main 上的 TODO。
 
-```bash
-npm install -g @michelj/context-guard --registry=https://registry.npmjs.org
-```
+它作为 Skill 安装到 **Codex**、**Cursor** 和 **Claude**。这一轮不开发新 Hook。
 
-只有当你明确希望安装 Codex 生命周期 hook 提醒时，才加 `--with-hooks`：
+[仓库文档与文件布局](docs/README.md) · [一页 Skill](SKILL.md)
 
-```bash
-npx @michelj/context-guard install --with-hooks
-```
+## 为什么这是另一种范式
 
-该命令也会在 `~/.codex/config.toml` 中启用当前的 `[features] hooks = true`，并把已弃用的 `codex_hooks` 别名安全迁移，同时保留其他配置。
+| 把对话当工作场所 | Context Guard |
+| --- | --- |
+| 历史在线程里 | 结构在 Map 上 |
+| 下一轮从零开始 | 下一轮打开同一张 Map |
+| 随便一个聊天里说「看起来可以」 | 人跟 Coordinator 确认 |
+| Agent 看见什么取决于粘贴了什么 | 执行 Agent 绑定到对应 TODO/Bug |
+| 记忆是对文件的检索 | 记忆是带版本与发布的项目状态 |
 
-npm 包正式发布前，也可以直接从 GitHub 使用：
+这不是又一份 prompt 包、RAG 目录，或「记住这个」插件。它是软件工作的 **人–Agent 操作环**：定位节点、确认意图、在 Session 中执行、验证，然后发布。
 
-```bash
-npx github:Michel-Johnson/Context-Guard-Skill install
-```
+Coordinator / Executor / Tester 的角色提示词用于拆开规划、执行和检查。角色文本不等于协议权限。自动多 Agent 编排仍在推进；产品本身是协作契约（Map、Session、授权、人确认、Main）。
 
-也支持手动安装：
+## 看工作台
 
-```bash
-git clone git@github.com:Michel-Johnson/Context-Guard-Skill.git
-cd Context-Guard-Skill
-mkdir -p ~/.codex/skills/context-guard
-rsync -a --delete \
-  SKILL.md README.md README.zh-CN.md agents references scripts tests \
-  ~/.codex/skills/context-guard/
-```
+人在工作台里看 Map。Coordinator 可以定位、游览和改结构。干活的 Session 不对人说话。
 
-安装后 Codex 应该能发现：
+**云端：** 配置 Cloud 后，它是唯一的人类工作台前端。本地服务负责同步和宿主投递。私有部署需要浏览器登录。设备每个项目登录一次，新 Session 复用该连接。
 
-```text
-~/.codex/skills/context-guard/SKILL.md
-```
+**本地：** 校验真实 Session 绑定并复用项目已有服务。首次配置、身份歧义和工作树迁移才需要人选择；已连接项目的新 Session 不必再选。
 
-## Context 保存在哪里
+### 总览
 
-Context 必须保存在当前打开的本地项目里：
+第一页 4–8 张主干模块卡。点一张进入。未修 Bug 在右侧列表。
 
-```text
-<Codex 打开的项目根目录>/.codex/context/
-```
+![工作台总览](docs/shots/workbench/overview.png)
 
-不要把 context 写到：
+### 进入模块
 
-- skill 安装目录
-- chat/thread 名称对应的目录
-- 临时目录
-- SSH 远程服务器路径
+开工单元挂在模块下面，只画从属实线。
 
-对后续工作有价值的短用户消息会保存在：
+![模块内部](docs/shots/workbench/module.png)
 
-```text
-<Codex 打开的项目根目录>/.codex/context/user-messages.md
-```
+### 模块关系
 
-如果用户提供了后续需要复用的凭据，Context Guard 只会在公开 context 中记录脱敏指针。原始凭据必须只保存在本地私有目录：
+「关系」高亮生产/消费伙伴，其余变暗，不会进入该模块。
 
-```text
-<Codex 打开的项目根目录>/.codex/context/private/
-```
+![模块关系](docs/shots/workbench/relations.png)
 
-如果手动运行脚本，建议显式传入项目根目录：
+### 会话流动
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
-```
+点一条挂了会话的 Bug。从根到该节点的链路亮起来，当前会话沿线流动。
 
-注册一个用户已确认的自动化测试：
+![会话流动](docs/shots/workbench/session-flow.png)
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-add \
-  --root /path/to/project \
-  --title "Markdown 预览渲染" \
-  --command-text "npm test"
-```
+### 授权模式
 
-创建一条待确认的功能链测试草案：
+「授权模式」可以标切片。灰卡可见范围是以后的事，不是当前默认。新 Session 默认看见自己这张 Session Map。
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-add \
-  --root /path/to/project \
-  --title "GPU 监控按钮" \
-  --entry "点击 GPU 监控按钮" \
-  --exit-check "打开包含有效 grafana_url 的监控页"
-```
+![授权模式](docs/shots/workbench/auth-mode.png)
 
-把 bad case 挂到功能链的具体环节：
+顶栏最右 **设置** 里切界面语言和主题。地图上的标题、用途、记忆仍按写入时的语言。
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-attach-bc \
-  --root /path/to/project \
-  --chain-id FC-... \
-  --node-title "后端返回监控 URL" \
-  --bad-case BC-... \
-  --check "grafana_url 不为空，前端不会卡住"
-```
+## 安装
 
-用户确认流程后，再批准同一条功能链：
+使用 npx 安装。安装器会检测 Codex、Cursor 和 Claude，把 Skill 与生命周期 Hook 一起安装并安全合并现有配置：
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-approve \
-  --root /path/to/project \
-  --chain-id FC-... \
-  --command-text "npm test -- gpu-monitor"
-```
-
-功能链命令可以输出 checkpoint 标记，让测试中台知道具体哪一步失败：
-
-```text
-CG_CHECKPOINT:后端返回监控 URL:PASS
-CG_CHECKPOINT:前端打开监控页:FAIL:缺少 grafana_url
+npx @michelj/context-guard install
 ```
 
-标记里的 checkpoint 名称必须匹配已登记的功能链节点；未知名称会被当成测试链路错误。已批准的功能链默认必须报告每个已登记 checkpoint，除非该 checkpoint 被明确标为 optional。
-
-如果某个 checkpoint 不适合每次都跑，显式标为 optional：
+也可以全局安装：
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-set-checkpoint \
-  --root /path/to/project \
-  --chain-id FC-... \
-  --node-title "前端打开监控页" \
-  --required optional \
-  --reason "只在浏览器集成环境运行"
+npm install -g @michelj/context-guard --registry=https://registry.npmjs.org
 ```
 
-查看每条功能链哪些 checkpoint 必跑、哪些可选：
+强制安装到三类客户端：
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-list \
-  --root /path/to/project \
-  --verbose
+npx @michelj/context-guard install --platform all
 ```
 
-如果用户说这条链不需要每次都跑，修改运行频率：
+默认会安装 Hook。只要 Skill：
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py feature-chain-set-policy \
-  --root /path/to/project \
-  --chain-id FC-... \
-  --run-policy relevant-only \
-  --reason "只在修改 GPU 监控流程时运行"
+npx @michelj/context-guard install --no-hooks
 ```
 
-开发完成后交给测试中台：
+默认目录分别是 `~/.codex/skills/context-guard`、`~/.cursor/skills/context-guard` 和 `~/.claude/skills/context-guard`。安装器会备份并合并现有 Hook/Settings；对 Codex 还会启用 `[features] hooks = true`。
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py dev-complete --root /path/to/project --jobs 2
-```
-
-查看只读测试中台页面：
+npm 包正式发布前：
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-test-hub --root /path/to/project --open
+npx github:Michel-Johnson/Context-Guard-Skill install
 ```
 
-简单管理测试：
+安装后，相应客户端应能在上述 Skill 目录发现 `SKILL.md`。
+
+然后，在真实项目里：
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-list --root /path/to/project
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-disable --root /path/to/project --test-id TC-... --reason "暂时不需要每次运行"
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-enable --root /path/to/project --test-id TC-...
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-set-policy --root /path/to/project --test-id TC-... --run-policy relevant-only --reason "只和编辑器改动相关"
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py test-hub-remove --root /path/to/project --test-id TC-...
+context-guard workbench --root /path/to/project --session <真实-session-id>
+context-guard doctor --platform cursor --root /path/to/project
 ```
 
-## 常用方式
+本地入口默认是 `http://项目名.localhost:1355`。绑定钉住命名 URL、Git 项目、后端和 Session；不会因为更新的任务自动切换。见 [命名工作台](references/named-workbench.md)。
 
-让 Codex 启用并维护 context：
+## 一轮怎么走
 
-```text
-Use $context-guard to maintain this task context.
-```
+1. **打开 Map** — 首次使用：人和 Agent 一起锁定第一层（卡名要一眼能看懂），再拆第二层、第三层。之后的 Session 打开这张图。
+2. **绑定 Session** — `context-guard workbench --root <项目> --session <真实-session-id>`。
+3. **授权切片** — 人标出这次 Session 可以读什么。
+4. **开工** — Agent 用 `map read` 读，用 `map apply` 写，必须带真实会话、基准版本和稳定操作编号。聊天附和不会写 Map。
+5. **确认** — 普通提案在工作台等待。
+6. **发布** — 经过验证的 Session 工作可以进入 Main。Session 草稿不是 Main。
 
-展示当前路线图：
+第一次 Session 若记录语言仍未设定，Hook 会要求 Agent 先问「中文还是 English」，保存后后续 Session 不再问。
 
 ```text
-Use $context-guard to show the roadmap.
+Use $context-guard. 共享 Map、隔离 Session、人确认、发布进 Main。
 ```
 
-初始化项目 context：
+常用命令：
 
 ```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py init --root /path/to/project
+context-guard workbench --binding-status --root /path/to/project --session <真实-session-id>
+context-guard workbench --list --root /path/to/project
+context-guard map read --root /path/to/project --session <真实-session-id> --node <id>
+context-guard doctor --platform codex --root /path/to/project
 ```
 
-设置记录语言：
+`record-bad-case` / `record-bad-case-fix` 关闭失败/修复闭环。`archive-session` 把耐久的 Session 结果写到 `owns` 覆盖且已确认的 Map 节点上；没有归属的文件保持未分类，直到人确认归属。
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py set-language --root /path/to/project --language 中文
-```
-
-生成路线图：
+Codex 安装 11 个生命周期 Hook（不含 `SessionEnd`）。它们在推理边界投递真实 Map、授权、待办/Bug 和其他 Session 的变更。用户的新要求写成 Map TODO。`TODO.md` 只由人维护。
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py show-roadmap --root /path/to/project
-```
+## 云端
 
-也可以用 npm CLI 作为轻量封装：
+配置 Cloud 后，它是唯一的人类工作台前端。同步基于事件（项目级 SSE），不是定时全量覆盖。开发前 `sync prepare`，验证后 `sync finish`。不相交的变更会重放；重叠的节点、字段或文件返回 `WORK_IMPACT` 并保持未验证。
 
-```bash
-npx @michelj/context-guard show-roadmap --root /path/to/project
-```
+服务端、Slack 和部署维护在独立的 [Context Guard Cloud](https://github.com/Michel-Johnson/Context-Guard-Cloud) 仓库。本仓库只维护 Skill、本地后端和宿主适配；公共运行库、工作台页面和角色资料由固定 Cloud 发布包生成。开发和打包前执行 `npm ci --ignore-scripts`、`npm run build:runtime`，不要修改生成文件。连接：[Cloud Sync](references/cloud-sync-interface.md)。记忆权威：[服务器记忆](references/server-memory.md)。
 
-创建支线任务：
+## 文档
 
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py create-branch-task \
-  --root /path/to/project \
-  --title "支线任务标题" \
-  --branch "支线名称" \
-  --parent-node NODE-YYYYMMDD-001
-```
+| 主题 | 入口 |
+| --- | --- |
+| Skill（一页，给 Agent） | [SKILL.md](SKILL.md) |
+| 文档索引 | [docs/README.md](docs/README.md) |
+| 工作台 / Map CLI | [工作台接口](references/workbench-interface.md) |
+| 角色（Coordinator / Executor / Tester） | [roles.md](roles.md) |
+| npm 发布 | [发布手册](docs/npm-release-runbook.md) |
 
-记录路线图节点：
-
-```bash
-python3 ~/.codex/skills/context-guard/scripts/context_guard.py checkpoint-roadmap-node \
-  --root /path/to/project \
-  --title "给 Codex 看的源标题" \
-  --display-title "给用户看的短标题" \
-  --user-request "用户实际提出的问题" \
-  --progress-summary "当前进展" \
-  --method-summary "采取的方法" \
-  --branch Main \
-  --level major \
-  --outcome "结果"
-```
-
-## 主要文件
-
-```text
-.codex/context/
-|-- index.md              # 快速索引和当前任务
-|-- roadmap.md            # agent 可读路线图
-|-- bad-cases.md          # bad case 登记表
-|-- preferences.json      # 语言和项目偏好
-|-- roadmap/
-|   |-- roadmap.html      # 用户查看的路线图
-|   |-- roadmap.md        # agent 快速读取版
-|   `-- roadmap.json      # 结构化索引
-|-- tasks/                # 任务级 context
-|-- task-cases/           # 任务导向测试 case
-|-- test-hub/             # 测试注册表、最近结果和失败证据
-`-- bad-case-tests/       # 可复用 bad case 检查脚本
-```
+本仓库把 **源码** 放在 GitHub `main`，把 **开发记忆** 放在用户指定的私有服务器。整个 `.codex/` 不进 Git 或 npm。其他项目不会继承本仓库的服务器配置。见 [RULE.md](RULE.md)。
 
-## 使用原则
-
-- 路线图只记录关键进展，不记录每个小动作。
-- 用户看的标题要像人话，不要像实现日志。
-- bad case 要能帮助未来避免复发。
-- 测试设计权属于人类；Codex 可以执行已确认检查，或提出待确认草案。
-- 当任务容易复发或适合沉淀为流程检查时，Codex 应温和提醒用户是否创建测试任务，但不能擅自创建长期测试。
-- 测试的长期单位优先是功能链：一个明确入口、一段真实流程、多个检查点、覆盖多个 bad case。
-- 新 bad case 优先挂到已有功能链节点；没有匹配功能链时，再提出新的功能链草案。
-- 功能链默认是 `proposed` 草案；用户确认后，用 `feature-chain-approve` 在检查覆盖完整时再批准。
-- 用户确认的测试默认是 `every-dev-completion`；只有用户要求时，Codex 才能改成其他运行频率。
-- 已确认的自动化测试应进入 `.codex/context/test-hub/registry.json` 或 `.codex/context/test-hub/feature-chains.json`，由 `dev-complete` 统一调度。
-- 测试中台保持简单：一个注册表、一个 `dev-complete` runner、一个最近结果、一个只读 HTML 状态页和几个管理命令。
-- Codex 最终总结必须说明当前测试中台结果：已确认的 always-run 测试是否全部通过、失败、阻塞，或当前没有这类测试。
-- 测试链路优先复用已有命令、脚本、截图或人工检查。
-- 不要为了每个 bad case 都新写脚本。
-- 前端或 HTML 改动结束前，应实际查看页面或截图，确认没有明显视觉错误。
-- 任何新的长期测试 case 都先写简短草案，让用户确认后再变成 active 测试。
-
-详细行为规则见 [`SKILL.md`](SKILL.md)。
+本地 `.codex/context/` 是兼容缓存和草稿，不是第二份权威。Cloud Agent 阅读面正迁向 [Memory Filesystem v2](references/memory-filesystem-v2/README.md) 的 node/module Markdown；在该投影真正暴露之前，不要假装能直接读取服务器私有文件。