@yijiancaotang/cli 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,280 @@
-# Temporary Holding Version
+# 一间草堂命令行
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+一间草堂 CLI 1.0.0。npm 包名为 `@yijiancaotang/cli`，命令为 `caotang`。
+
+## 接入
+
+给任意 AI 复制同一句话：
+
+> 帮我接入一间草堂。运行 npx @yijiancaotang/cli@latest setup，告诉我怎么批准。
+
+`setup` 没带名字时会提示 AI 以自己的名字补上 `--agent <你的名字>`；不会自动选择身份、申请连接或借用其他 AI 的钥匙。名字是自由文本，去首尾空白、最多 80 个字符，拒绝控制字符；大小写和普通空格差异视为同一名字。手动终端可自报“命令行”。
+
+每条需要连接的命令都带同一个 `--agent` 名字。下面以 Codex 为例，其他 AI 换成自己的名字：
+
+```sh
+npx @yijiancaotang/cli@latest setup --agent "Codex"
+caotang --agent "Codex" doctor
+caotang --agent "Codex" projects
+```
+
+同一电脑的不同 AI 分别在网页批准一次；再次接入只复用自己的连接。已知平台安装的技能会固定带上本次名字，不把一把钥匙发给多个 AI。`--platform` 只选一个已知平台安装技能；名单外 AI 不装技能，按 setup 返回的通用命令说明使用。确认接好后提示：“开个新对话，说‘开工了’。”
+
+本机连接按环境和 AI 名字分开保存。现有旧文件和验证接口没有可靠平台名，旧共用钥匙归“命令行”，仅显式 `setup/auth login --agent 命令行` 时懒迁移；原文件不改写、不删除，其他 AI 不读取它、各自接入。网页吊销一条连接或当前名字运行 logout 不影响其他 AI。
+
+默认生产入口为 `https://caotang.gtcai.cn`，明确选择测试环境时才带测试参数；不自行切换环境。每个 AI 的设备授权须由本人在网页分别批准，连接和动作归属可在工作台与 Agent 管理页查看。
+
+## 本地开发
+
+需要 Node.js 20 或更新版本；凭证文件安全目前按 POSIX 权限设计，Windows 文件权限未验收。
+
+```sh
+npm run build:agent-cli
+node apps/agent-cli/bin/caotang.cjs --help
+npm run test:agent-cli
+```
+
+测试只使用临时目录、合成令牌和 loopback HTTP fixture，需要本地监听权限；不需要 Go、数据库、Redis、云账号或实际网页登录。
+源码构建后才运行全套测试，不用旧 dist 代替新构建。业务请求默认生产公开入口，`--env test` 切到测试入口；不要在未授权环境试写。
+
+### 按需加载
+
+每个新对话第一件工作前（改报价、写邮件、写代码都算），即使未提草堂也主动短读一次；闲聊和纯问答不读。只选 `caotang-context`，已有可信短读就复用，不为开工加载第二技能。接入同意/拒绝门优先，不靠用户说“开工了”触发。第一条命令直接短读，不先运行 `command -v`、`env`、`auth status` 或 `ToolSearch`；出错后才排查。沿用接入时用户已选环境，正式版默认生产，不重新确认环境、不自行切换；明确使用其他环境时保留本次已选参数。
+
+若本人明确限定只用 caotang 命令，就不使用 MCP；不改配置，误调用其他入口即停。
+
+`caotang-workday` 只负责完成重要工作/收工，不再包含开工短读或引导加载第二技能。正常开工不跑doctor；仅出错且需要安装诊断时使用。用户明确要接着某个项目且短读不足时才查详情，短读能回答就不扩查。
+
+`caotang-save-knowledge` 只在写入时加载。字段、长度和JSON例子按当前动作读取现有专属 `--help`，不预读整套帮助、不新增参考工具；公开、删除、本人确认、不读凭据、权限、待审、未知写与长势确认仍留在技能正文。技能描述是触发指引，不是“每次开工都会读”的实测保证。
+
+本机安装不等于真实 AI 的业务验收，也不证明输入/输出 Token 消耗。AGENTS.md、CLAUDE.md 等常驻用户配置不写；如需另行修改，须取得本人明确范围许可。
+
+## 安装与诊断
+
+| 命令 | 行为 |
+| --- | --- |
+| setup --agent 名字 [--platform 平台] [--no-open] | 独立接入该 AI；platform 只给一个已知平台安装技能；无名字提示下一步，不申请连接。 |
+| doctor --agent 名字 [--platform 平台] | 只读检查该 AI 的技能、独立连接和实时有效性，不安装、不启动 AI 客户端。 |
+| version / --version | 离线返回包/Node版本及 `release_status=released`，不读取凭据、不构造网络客户端 |
+| update | 只返回“运行 `npx @yijiancaotang/cli@latest setup --agent <你的名字>` 更新到最新版。”；不查 registry、不下载、不自动升级。 |
+
+稳定CLI由安装器维护受管副本；路径不是给 AI 搜索凭据的入口。PATH 找不到 `caotang` 时，直接用固定路径 `~/.local/bin/caotang`，保留原参数与环境；不猜路径、不翻 `~/.caotang`、不读任何凭据，不扫描目录找命令。不改 shell、PATH、MCP 或权限；固定路径也失败就如实说明。只有命令出错后确需查连接状态时才用 `caotang --agent "Codex" auth status`，不作开场预检。`command.executable_path` 仍保留在运行输出中；不因缺 PATH 要求改配置或额外探测。
+来源构建的bin/dist/skills组成封闭复制集，不携带源码、测试、配置或凭据。稳定副本不依赖临时来源继续存在。
+
+本机锁只面向同一主机/PID命名空间的本地常规文件系统，不支持共享网络盘。固定单文件追加申请/释放记录，按先后顺序仅首个未释放的活跃或未知持有者占有；只跳过已确认死亡者，不删除、改名、截断或调用外部程序。没有16次崩溃或64KiB准入耗尽；文件数量固定，但日志字节和读取工作量随使用增长，不声称磁盘体积恒定。保留旧协议标记，活跃、未知或不安全旧标记继续拒绝；不能与旧改名/压缩协议进程并发混跑。未知旧目录/损坏记录不自动修复。文件系统的保护规则可能阻止本地安装，请按实际诊断核对。
+
+支持 Claude Code、Codex、OpenClaw；`kimi-code`、`kimi-work`、`workbuddy` 仅支持macOS本机安装。平台检测只检查程序元数据，不运行客户端；`kimi-code`可检测PATH中的 `kimi` 或桌面bundle，`kimi-work`与`workbuddy`不支持PATH命令检测，不能把 `kimi` 当作工作模式。每次只选一个 `--platform`，非macOS拒绝这三项；安装只面向当前名字对应的平台，未检测到程序不能报ready。未选新平台的技能根异常不得阻断旧平台。
+六项 canonical 技能（开工续接、沉淀知识、项目进展、查找、完成收工、首次接入）与manifest继续作为共用来源。各平台沿用相同的按需加载和安全确认边界，不改 MCP 配置，不提供卸载命令。
+
+| 平台 | 用户级技能目标 |
+| --- | --- |
+| Claude Code | `CLAUDE_CONFIG_DIR/skills`，默认`~/.claude/skills` |
+| Codex | `~/.agents/skills`，不向CODEX_HOME私有目录安装 |
+| OpenClaw | `OPENCLAW_STATE_DIR/skills`；否则`OPENCLAW_HOME/.openclaw/skills`，默认`~/.openclaw/skills` |
+| Kimi Code（`kimi-code`，仅macOS） | `KIMI_CODE_HOME/skills`，默认`~/.kimi-code/skills`；覆盖根须为本人HOME内的安全绝对路径。PATH命令 `kimi` 或bundle `Kimi Code.app/Contents/MacOS/Kimi Code`；该入口不写共享`~/.agents` |
+| Kimi.app 工作模式（`kimi-work`，仅macOS） | `~/Library/Application Support/kimi-desktop/daimon-share/daimon/skills`；bundle内执行文件 `Kimi.app/Contents/MacOS/Kimi` |
+| WorkBuddy（`workbuddy`，仅macOS） | `~/.workbuddy/skills`；bundle内执行文件 `WorkBuddy.app/Contents/MacOS/Electron` |
+
+覆盖目录必须是本人HOME内的绝对路径；不读客户端配置或凭据，不写workspace、Gateway或系统目录。目录检查属主、权限与链接；目标文件不覆盖个人内容。
+重复相同版本不改CLI/技能或另领授权；安全且完全为空的同名技能目录可补齐，已有内容/额外文件/未知同名命令/修改后的bundle失败关闭，不自动删除或强制更新。
+变更使用无异步间隙的父目录inode绑定与独占新建，不覆盖旧文件；新文件先为000，持句柄写完并校验后才开放最终权限，开放后再核内容和权限。局部失败仅通过自建fd尽力降回000，不按可能已被替换的路径修改文件；文件系统若拒绝降权则不能保证恢复，先保留现状并人工核对。
+中断可能留下部分安装或锁，未完成文件不应运行；不自动清理，不承诺多文件事务或SIGKILL恢复。
+
+doctor的JSON位于`data`：`ready`、`issues[]`、`next_actions[]`、`command`、`platforms`、`auth`（status/source/kind/scope）、`network`。
+`readiness_scope=local_cli_and_skills`和`end_to_end_verified=false`明确不代表AI会话已读写业务。缺凭据时network=not_checked；断网不重签，401不删凭据；setup交付未知保留网页核对/吊销指引，不重新领取。
+
+`setup` 的 `data.authorization_attempted` 表示本次是否实际调用了新设备授权的开始请求。复用已有有效授权，或在发起前因读取/验证/取消失败时为 `false`；已发起后即使遭拒、断网或结果未知仍为 `true`。它不表示授权成功，成功与否以最终 `auth`、`issues` 和退出码为准。
+
+### 接入对话
+
+首次按当前 AI 是否第一次安装技能判断；新授权不等于首次，同一个 AI 已有连接但首次安装技能时仍可能是首次。`data.onboarding.newly_connected_platforms` 仅列本次首次接好的入口，不包括已装重复 setup、恢复或更新。核对当前 AI 的入口，不能把其他 AI 的首次状态套过来。认证和 ready 原字段保留，开场字段不是接入成功证明。
+
+`data.account_state` 只含 `empty|has_content|unknown`，不带任何内容，不为判断空账号先读工作台；`data.onboarding.action` 为 `introduce|ask_once|none`。技能转述 `data.user_message` 的 CLI 固定人话，不贴字段名或账号 ID，包括 `auth.status`、`read_only`、`ready` 等，不让模型编造状态；用户问细节时才给必要说明。缺字段、矛盾或入口不明时不猜、不自动读写。
+
+CLI 给用户看的话以统一接入提示为准，只含固定文案和已验证的 URL、确认码格式化；技能和接入页用同样的说法，不各写一套。不主动介绍功能或堆卖点；用户问“能做什么”时才说明。AI 可按语境调整，但不能变长，不能贴字段。introduce 保留为动作标记，不要求功能介绍；下表只说明行为边界，短句按统一文案输出。
+
+| 场景 | 状态 / 动作 | 对话行为 |
+| --- | --- | --- |
+| 首次且空 | empty / introduce | 有写权限才用短句问是否保存；同意整理后只用当前对话拟私有条目，具体条目明确同意才写，没有素材不凑数。 |
+| 首次有内容 | has_content / ask_once | 问一次是否读工作台，说明内容会发给当前 AI 服务，同意后才读。 |
+| 首次未知 | unknown / ask_once | 不说账号空；同样问一次并说明内容会发给当前 AI 服务，同意后才读。 |
+| 已装重复 setup | 任意 / none | 只说“已经接好了，不用批准。”，不介绍、不问、不读。 |
+| 日常新工作对话 | 不在接入对话 | 维持一次短读与按模式简报。 |
+
+接入对话优先于 context 的自动短读；workday不承担开工。不同意、沉默或含糊不读，本对话不再问，不换搜索/详情/MCP绕过。本人之后主动明确要求读取时，只按新授权范围操作，不能当写入同意。短读只含规矩、有效待确认和有限近期记录，不含全量项目、知识、历史；只看可信 `account_state` 或 `account_empty` 判断空，不由空数组、缺权或部分结果推断全账号空，不主动建议清理。
+
+`read_only` 只能读，不能承诺写或发写类申请；只读不提保存，也不问“要存几条吗”，按统一文案的只读分支说明。本人要求时可留对话内草稿。只读需要改权限时说“改权限要在网页重新批准一条连接。”账号开关仍须到 Agent 管理核对读写权限，由本人处理，不自动更换连接；只读不能靠反复 `auth login` 升级。不能把 `auth login` 说成重新授权或升级权限的办法。不换工具、代签或自行扩大权限。
+
+已复用连接，用户问“怎么批准”时，只说“已经接好了，不用批准。”不发批准链接或码，不要求再次 login。已有有效连接再次运行 `auth login` 时只会复用、不新签。
+
+Codex、Claude Code 已证实新对话能读取技能；不由安装成功推定全部技能已生效或真实读写全部通过。OpenClaw、Kimi Code、Kimi.app 工作模式、WorkBuddy 保守提示“如果看不到技能，开新对话或重启应用”，由本人操作，不能要求 AI 自动重启。
+
+## 授权与输出
+
+每个 AI 只使用自己的连接；以下以 Codex 为例，连接须由本人在网页批准：
+
+```sh
+npx @yijiancaotang/cli@latest setup --agent "Codex"
+caotang --agent "Codex" auth status
+caotang --agent "Codex" auth logout
+```
+
+login 只走浏览器确认码，不接收密码。stderr 按行输出安全JSON事件（核码信息、必要时末行错误），stdout 只输出最终安全身份/scope；token、device code 和上传 nonce 不进入输出或子进程参数。
+仅本人刚在自己的电脑/AI发起接入时才允许，别人发来的码拒绝；平台不主动索码，设备名/请求方自报未核验。
+等待批准、确认码过期、拒绝、未知和断开的用户提示均转述 CLI 的统一短句；链接和确认码只用 CLI 已验证输出，不补营销段或一次念出全部排查步骤。对安全状态查询允许有效期内有界恢复；交付未知或保存失败不自动再领，令牌只交付一次。`authorization_delivery_unknown` 按短句先请本人到 Agent 管理看有没有连接，后续需要时只用 `caotang --agent "Codex" auth status` 查本机；已有而本机未保存的连接由本人核对并处理或吊销，再决定重新接入。失效或断开不自行重签。
+
+请求方和连接默认名都是 AI 自报的 `--agent` 名字；电脑名称只用于需要的设备提示，不代替 AI 身份。名称是自报，旧连接名不批量改写。
+凭据文件仅由 CLI 管理，目录0700、文件0600；拒绝符号链接、硬链接、宽权限、错误owner/origin和并发覆盖。按环境和规范化名字隔离保存于 `~/.caotang-credentials/`；不是让 AI 打开的配置文件。旧正式凭据只读保留；仅命令行名字显式 setup/auth login 时无覆盖复制并读回验证，安全认领标记防止退出后重新复制旧钥匙；失败不丢原凭据，其他名字不读取旧源。AI 不读取任何凭据或迁移内容，只用安全状态命令查询。目录隔离和禁读只降低误读风险，不是同用户强隔离；钥匙串未实现。
+如果用户目录、其父路径、凭证目录或凭证文件含符号链接，会说明链接原因并返回`credential_symlink`，请由本人改用真实路径后重试；不要自动删链接、迁移凭证或放宽权限。其他属主/权限等问题仍按各自安全诊断处理，`doctor`/`setup`不因此发起新授权。
+`CAOTANG_CLI_DEV_TEST_TOKEN`、`CAOTANG_CLI_DEV_PRODUCTION_TOKEN` 可分别覆盖对应环境，覆盖值不落盘；未绑定环境的通用变量被拒绝，不支持 `--token`。
+不要将变量值、凭证文件或确认响应贴进聊天、日志或命令参数。status 实时验证；`auth logout` 吊销当前连接，只断开当前名字对应的 AI，不影响其他 AI，操作前说明影响并取得本人明确同意；manual token 在网页管理。重新接入运行 `setup --agent <你的名字>` 并由本人批准；已有有效连接时复用、不新签，不把再次 login 当新入口标记或权限升级。
+只有确认撤销或收到401才清理匹配的本地文件，环境覆盖不删除另一个文件。安全的空锁文件会通过原追加票据恢复；损坏或未知锁失败关闭，不自动删除锁或凭证；先确认没有同环境命令运行，再由你人工核查，不确定时保留现状。
+原开发目录`.caotang-cli-dev`若存在，不自动读取、导入、移动或删除；请先在网页核对旧设备后自行决定是否吊销/重新接入。环境覆盖变量保持原名，不随本轮三个名称的确认而改变。
+
+默认每次 stdout 为 JSON `{http_status,data}`；`--human` 在安全缩进JSON之外，用单独中文说明已知的权限缺口，仍保留原状态和字段。它只解释协议中的缺失段，不把任意卡片正文当权限元数据。
+写命令明确返回 202 结果未知（`write_outcome_unknown` 或无冲突的 `write_status:unknown`）时退出 6；真实回执仍写 stdout。待审核或已受理的 202 退出 0，只表示收到请求，不表示业务已完成。两步推进不能仅靠 shell 的 `&&`：第一步待审或未知，都要停下核对。204不合成业务对象；`audit_pending/audit_recovery` 保留。上传grant的待恢复审计在 `operation_audit` 单独标记阶段，不冒充附件结果。
+一般失败写 stderr `{code,message,next_action,...安全字段}`；setup/doctor能形成诊断时写stdout的issues/next_actions并返回非0，challenge仍只在stderr。退出码：2参数/输入或本地未就绪，3未授权，4权限，5限流，6网络或结果未知，7服务/协议，130取消。
+
+## 命令
+
+### 开工、收工与我的规矩
+
+- `caotang --agent "Codex" context --start` 做一次短读，不与旧 `context --since` 筛选混用。始终沿用当前账号/环境。除规矩外，每个段落受自己原有的读取权限控制；最近 **三个有记录的北京时间日期**而非最近三个日历日，每日最多 3 条、每条摘录最多 120 个字符；等待本人确认的申请最多 3 条。只在确切可见的本人项目进展中取最新的独立 `【下一步】` 标记。隐藏、不可用和 0 分开解释，不扩大读取。
+- 本人的有效令牌（包括只读）可 `caotang --agent "Codex" rules` / MCP `get_my_rules`，开工也能读到；**没有 Agent 写规矩的命令、工具或待确认申请**。增删改仅在网页“我的规矩”，最多 20 条，每条 200 个 Unicode 字符；不要填写任何秘密。规矩是偏好，不是授权。
+- CLI 只按环境、已核账号及北京时间日期决定简报长短，不记业务内容、对话或授权证据。缺少可信状态/访问失败时保守用简短模式；MCP `get_start_context` 一律简短，并提示“要详细就说一声”。用户说这次别问就不再提；长期不汇报/不询问可由本人写进规矩。敏感信息先去除，不自动重新授权/安装启动钩子。
+- `caotang-context` 独占开工/续接短读，短读不足且任务确需知识时才检索复用结果/开花卡，引用真实环境出处。`caotang-workday` 只在完成重要工作或收工时整理候选，让本人挑要记录的项目进展/知识/认知，明确同意才写。独立进展正文 `【下一步】具体动作` 仅保存本人同意的下一步；未确认写入保留去敏建议，不自动重试。
+- `caotang-first-connect` 按上方接入对话规则分流，不看是否新授权、不预读内容判空。MCP 无可靠首接标记，仅本人明确说刚接入时问一次并说明内容去向；不查回收站、本机文件或其它会话。六技能安装/核验不代表真实模型已完成验收。
+
+列表查询：`projects`、`knowledge`、`search`、`progress list ID`、`checkins`支持`--limit 1..50`（默认20）和`--offset`；返回真实过滤后`total`、`has_more`、`limit`、`offset`，空页不丢总数。项目详情仍只附最近10条，`updates_total`才是完整数量，全部记录从`progress list ID`翻页读取。排序按选定时间倒序，再按ID倒序；同次响应计数与当前页一致，但分次翻页不是冻结快照，期间有写入可能改变页面。
+
+上述列表支持`--start-date YYYY-MM-DD`、`--end-date YYYY-MM-DD`，按北京时间包含首尾日期，可只给一侧，不可空值/倒序/无效日期（年份0001..9999）。项目/知识默认按`updated_at`，可`--date-field created_at`；项目进展与手写进展固定`created_at`。这不是`context --since`简报游标。MCP对应`list_projects`、`list_knowledge`、`list_project_updates`、`list_checkins`使用同名下划线参数；普通列表不设一年跨度限制，日汇总另按下文双日期/一年合同。`projects --core-only`、`knowledge --core-only` 和 `search --core-only` 只看核心；MCP 对应 `core_only: true`。进展列表本身没有这个筛选。
+
+统一搜索：`search [query]` / MCP `search`一次请求项目、项目进展、知识卡和本人手写进展；可省词按日期浏览。非空查询最多200 Unicode码点；空白拆词、全部命中、顺序不限、不分大小写，`%`、`_`和反斜线按原字符查，不要自行加SQL转义。项目查标题/简介/认知摘要，知识查标题/摘要，两类进展查本人可读正文，不扩到来源或父项目标题。
+
+`search`的items改为带`kind/id/snippet/created_at/sort_time`的跨类结果，不再都是知识卡DTO。title、updated_at和项目关联只在真实且可读时提供；片段最多240码点，省略号表示截断，不是全文。需要原知识DTO仍用`knowledge --q`或MCP`list_knowledge(q)`，也使用同一多词规则。`--status/--topic/--publication-status/--project`在统一搜索里**仅筛知识分支**，不会限制项目/进展结果；定向项目进展用`progress list ID`。`--date-field`只影响项目和知识，进展仍按创建时间。统一结果按时间、ID倒序再kind稳定排序。
+
+统一搜索按同一次授权逐类过滤：读项目或读知识任一开启即可，另一类没权限会返回partial/missing_sections；都关时403，不把缺权说成空库。受限知识应用正文不会进入搜索总数，独立进展列表仍保事件计数。权限内先固定去重，再匹配/日期/分页：明确来源优先，旧记录仅完全四元组+progress+唯一1:1去重，有歧义保留并给`historical_mirror_ambiguous`提示；不修改历史。项目和知识返回布尔 `is_core`，普通查询的进展省略该字段；筛选参数为 `--core-only` / `core_only`，不是 `core` 或 `is_core`。
+
+日汇总：`activity --start-date 2026-11-01 --end-date 2026-11-05` / MCP `get_daily_activity`，一次GET `/m1/activity/daily`。两侧日期都必填，按北京时间含首尾、最多一个日历年；不是固定366天。2024-02-29到2025-02-28可用，2026-01-01到2027-01-01含首尾则超限。只另接`--limit 1..50`（默认20）和安全`--offset`，不接关键词/项目/长势/core/date-field等筛选。
+
+返回`days`包含范围内每天的progress/knowledge_created/knowledge_growth、redacted_progress_count及knowledge_growth_coverage；`items/total/has_more`仅覆盖可读事件，items为当前页，days不随翻页缩小。每天progress=当天全部可读进展数量+redacted_progress_count，不能用当前页items长度来核对该等式。匿名数没有事件占位项、ID、精确时间、关联、长势或正文；growth明细只有真实from/to及当前可读卡片信息，可省snippet，不是历史正文快照。
+
+关闭读取项目时progress与redacted为null；关闭读取知识时知识两数及coverage_start为null、coverage=unavailable；两者都关403。草稿读取关闭时，草稿项目进展/checkin和草稿知识均在计数前过滤，partial/missing说明范围，不给被过滤条数。仅父项目可读的knowledge_applied正文受限仍保匿名日数。hidden/foreign父checkin保本人记录并遮父派生信息；先权限再固定配对，规则与search共用，但不把匿名计数资格带进search。
+
+coverage_start是实际开始记录长势事件的起点：之前的日桶knowledge_growth=null/coverage=not_recorded，起点日partial，之后complete；可读却缺coverage记录会失败，不编起点或零。partial、null、空明细或超末页都不能解释成当天没有活动，0也仅指本次可查范围没有记录。日汇总没有旧状态倒推或日历界面。
+
+`checkins`只读本人的手写进展：读取项目关闭时拒绝；自己的项目草稿在读取草稿关闭时整条过滤并说明缺口；未关联项目的记录保留；他人/隐藏等不可读父项目只保本人正文、时间及编号，不返回父项目标题，也不伪称开关关闭。项目进展中的知识应用事件在读取知识或草稿关闭时遮正文但保事件/数量。缺口不等于没有记录，不能换入口绕过。
+
+知识列表和搜索的 `--status` 使用 `captured`（播种）、`summarized`（生根）、`applied`（发芽）、`reviewed`（开花）、`templated`（结果）；无筛选时省略该参数。未知值会报参数错误，不再作为“没有知识”返回。草稿使用 `--publication-status draft`，与长势不同。
+
+`projects`、`knowledge`、`search` 的 `--limit` 范围为1至50；`context`、`pending`为1至100；`--offset`为非负安全整数（0至9007199254740991）。`--offset -1`与`--offset=-1`都会提示这个范围，不会发送请求；未知/重复选项仍拒绝。读取404时提示检查内容ID/列表及访问权限；写入失败和交付未知继续要求先核对实际结果，不能自动换键或重复写入。
+
+长势推进：`advance`只能逐级前进，同级与后退允许。409 `knowledge_stage_step_required`明确未执行跳级；有读取资格时保留`current_status/next_status`并提示当前/下一可用级数，无读取资格只说明缺口。不要自动连发中间级、重试或重新授权来绕过。`source add`只添加来源，不代替推进；公开审核也遵循这个能力划分。
+用户说某张卡已经用上时，可以主动问一次：“你把这张卡用在这个项目，做了这件事，要记为发芽吗？”复述已知事实，只问缺的；未来打算、沉默、拒绝或只报项目名都不是同意。没有项目或尚未关联，先问要不要新建或关联，不同意就不推进。播种到发芽先说清“先生根、再发芽”，本人明确同意两步后才逐级调用；第一步未确认成功不发第二步。第二步明确失败只报最后确认的级别；待审或结果未知说明哪个结果未确认，不自动重试。
+
+从生根进入发芽必须带 `source_type=project`、已关联的本人项目 `source_id`、一句本人确认的实际使用说明 `evidence_summary`；同时需要写知识长势和写项目进展权限。状态、应用证据、项目时间线一起写入。网页从发芽以下直接跳到更高级也要填写这一表单。退级、同级、已发芽后的推进不要求补项目或说明；不回填历史。
+
+项目的“核心”是本人设置的标记；知识不设星，发芽、开花、结果才算核心。只看核心的搜索不含进展，不代表没有进展；要看核心项目的进展，先找该项目再查进展。意图明确直接查，含糊就在对话里解释并问清。 `link --core` 是保留的关联参数，不设核心标记。只看核心项目默认不含归档；`projects --core-only --status archived` 可显式查询。统一搜索的 `--status` 仍只筛知识。
+
+新建与来源整包：`knowledge add`、`project create`可显式传`--idempotency-key`（MCP对应idempotency_key，传HTTP Header而非业务JSON），沿用16–128位ASCII字母数字和`._:-`。按owner+工具隔离，不按设备；同键规范化内容相同不重执，不同内容409 idempotency_conflict。客户端不自动生成/换键/去键重发；无键仍不能承诺请求级防重复。异键同名是duplicate_title未创建，不是成功命中。新键成功须核request_id/idempotency_replayed/write_status；无法核实或响应无法解析时可能已写，不得自动重试。
+
+新知识可在同一个JSON请求带`sources`：省略/[]等价，null拒绝，最多20项且不截断，顺序与重复项都保留并纳入hash。每项用现有evidence_type/source_type/source_id/source_url/source_title/excerpt/file_key/summary，不接受owner、卡ID、长势或派生标签；字段按Unicode码点限额，source_url只收http(s)，不静默补协议。新卡、全部来源及显式主关联同一事务，任一来源失败不留半包；不能先建卡再循环source add模拟。已有卡的新来源仍用source add，不能重复追加刚随新卡保存的同一批。origin_url仍兼容，但不是结构化来源。来源不改长势、不自动关联来源指向的项目；非空file_key始终须本人且已存/可挂接，配额和删除围栏不变。
+
+非空sources要求写知识卡和写知识来源同时开启；来源权限不足时本次不新建，不能自动丢来源或把链接塞回正文。知识草稿可用`knowledge --publication-status draft`，需read_knowledge+read_drafts；项目草稿用`projects --status draft`，需read_projects+read_drafts，默认项目列表在有权时可含草稿。只有首次明确成功的draft_notice才提示新建草稿；202/unknown/replay不这样说。精简ID回执/读取缺口不是保存失败；已知succeeded但audit_pending只是审计待补，不重复业务。
+
+`knowledge add`、`project create`、`progress add` 的 `visibility` 只接受 `private` 或省略；`public` 在发请求前拒绝，不能静默改值重发。MCP 的 `create_knowledge_card`、`create_project`、`add_project_update` 同样只写私有。知识卡或项目公开须按本人明确意图走 `request visibility` / `request_public_visibility_change`，由本人网页确认；仍受“删除或归档申请”开关控制，默认关闭。进展没有独立公开申请入口，不把父项目的公开申请说成进展已公开。`publication_status=published` 是非草稿状态，不等于公开；`update_*`、项目阶段、知识长势、关联和幂等重放不能绕过确认。已有公开内容不自动转私有，读取筛选和申请中的 `public` 保留。403 `direct_public_write_forbidden` 使用固定说明，不输出后端任意正文，也不要求重新授权。
+
+幂等回放不缓存整份响应：按当前owner/live及本次读取资格给资源，原请求或当前为草稿都保护；内部公开暂存草稿不当用户请求草稿。source_count是当前数，不是原批次清单。Pending/Block回放是原不可变回执，当前审核请网页核对，不新建刷新状态机或重提审核。历史公开整包回执可能对应完整私有候选，不代表当前已公开；不以旧回执再次提交public。无键新create的明确Commit确认丢失为202 write_outcome_unknown；有键沿write_pending/request_id核对。历史公开中途失败若phase=publication/private_candidate_may_exist=true，只说明原公开流程未完成，不能说完全没保存/整体回滚。保留此类回执解析不表示客户端还支持直接公开。
+
+仅Agent知识create/update本次提交的summary/intent拒有效http(s)网址（不需空格）、www域名和8平台域/点子域后带路径的短链；普通裸example.com、无路径douyin.com、邮箱、文件名、版本号和平台名不拦。未提交字段不扫旧内容，原样重提交含链接字段也拒；网页手写/历史数据不自动改。平台标签source_platform只按实际可见source_url的解析hostname离线派生，遮URL也遮标签；只表示域名类别，不验证可达性或内容真实性，不跟随跳转或抓取。
+
+| 命令 | 输入 |
+| --- | --- |
+| context | --since / --limit；工作台与briefing，不是后续“续接”接口 |
+| projects / project ID | 列表支持 --status / --limit / --offset及上述日期参数；详情附最近10条和updates_total |
+| project create | --input JSON文件或-；title、summary及既有可选字段；可显式--idempotency-key |
+| project update ID | --input；仅title/summary至少一项，省略保持；不接受status/visibility/归档等字段 |
+| progress add ID | --input；body；可传 --idempotency-key，16-128安全ASCII，保持原键，不自动生成替换键 |
+| progress list ID / checkins | 完整只读列表；--limit / --offset / --start-date / --end-date，时间固定created_at |
+| cognition set ID | --input；cognition_summary |
+| stage set ID | --input；仅提供要修改的stage/stages/status，不补默认字段 |
+| knowledge / knowledge show ID | --limit / --offset / --topic / --project / --status / --publication-status；knowledge另可--q |
+| search [词] | 四类统一查询，可省词按日期浏览；--limit / --offset及日期参数；--topic / --project / --status / --publication-status只筛知识分支 |
+| activity | --start-date与--end-date必填、最多日历年；--limit / --offset只分页可读items，不截断days日桶 |
+| knowledge add | --input；卡片字段及可选sources<=20；可显式--idempotency-key，单请求原子保存 |
+| knowledge update ID | --input；仅已确认字段，不回填省略字段；本次summary/intent遵守正文链接规则 |
+| source add ID | --input；一个结构化来源，不抓取URL或解析正文 |
+| link 卡ID 项目ID / unlink 卡ID 项目ID | `--core` 仅作兼容关联参数；既不设置项目核心，也不为知识加星。 |
+| advance 卡ID | --input；internalization_status及既有证据字段 |
+| upload 本地PDF --card 卡ID | 可--source-title / --summary；本地普通文件1-10485760字节，不接受URL/目录/符号链接/标准输入 |
+| pending | 默认只列有效pending，--status all查看包含已处理/失效的历史，也可confirmed/rejected/expired；--limit 1..100（默认20）/ --offset；返回total/has_more，不代替网页确认 |
+| notifications | --filter all/unread/read/agent、--limit 1..50；需要读取通知权限 |
+| drafts | --limit 1..50；需要读取草稿权限 |
+| request delete / request archive | --input JSON文件或-；只建立知识卡或项目的删除/归档待确认申请 |
+| request visibility | --input JSON文件或-；只建立改为public/private的待确认申请 |
+
+JSON文件/标准输入最多1MiB，只接受对象；文件必须是普通文件，FIFO不阻塞读取。业务显示文本长度与Go一致按Unicode码点计数。
+
+项目编辑复用网页校验：去除Go Unicode White_Space，标题2–80码点、简介≤280；非草稿简介不能为空。已有归档项目可改文字但不改变归档状态，hidden/别人的项目不可改。公开项目仍走原审核与版本校验；冲突、已变化、校验失败都不是保存成功。读取关闭可写，但成功只返回允许的ID/结果/缺口。
+
+`project update`和`advance`不支持幂等键；CLI/MCP不发送，HTTP携带任何Idempotency-Key会在业务/动作日志写入前拒绝。明确Commit回执丢失返回202 `write_outcome_unknown`/`write_status=unknown`：只表示结果待本人网页核对，不是成功、失败或有后台恢复队列。无键手动再发不具备防重复保障，stage带证据可能重复添加证据；不要自动重试、换键或补写。进度`progress add`原强幂等合同不变，新create收据不扩到这些PATCH。
+
+`request` 输入仅接受 `target_type=knowledge_card/project`、目标UUID `target_id`、非空 `reason`（最多1000码点）；公开性申请另填 `visibility=public/private`，可选 `expires_in_hours` 为1至168整数。动作、权限和工具名由CLI生成，不接受确认参数、伪造owner或幂等参数。只有匹配的202待确认回执才说明“申请已创建，等你在网页确认”；这不证明目标归属已经核实或目标已经改变。回执不匹配或结果未知时先在网页核对，不自动重试、换键或重复申请。
+
+三类申请都受“删除或归档申请”控制，默认关闭，只读设备一律不能发起；“对外动作申请”仍只管社区。任一待确认开关关闭成功后，其下尚未处理的申请失效，重新开启不恢复旧申请，必须重新发起。关闭和确认按提交顺序处理，已先处理的历史不回滚。确定提交前锁忙返回失败；提交结果未知时必须先核对，不能声称回滚或建议自动重试。
+
+网页 `/app/pending` 可切换“待确认 / 已失效”，失效记录只读、无确认/拒绝按钮、不计待确认数量，社区历史仍受原开关隐藏。CLI `pending`及Agent MCP读取默认只列有效未处理，显式`--status all`查看历史；Web会话接口未随此修改。总数按同一可见范围的有效状态计算，不以返回数组长度充当总数。
+
+### PDF服务端校验
+
+上传边界：即使绕过CLI、用正确文件名/MIME/长度直接上传，服务端仍检查PDF头；非PDF固定返回400 `invalid_upload`，不应按服务暂不可用反复重试。不新增文件解析、自动重试或上传能力。
+
+### `context` 部分可用与读取边界
+
+长势显示：知识DTO保留原长势枚举，在可读状态旁给出 `growth: {label, description, level, total}`。真实长势事件的 `from_growth/to_growth`、逐级拒绝的 `current_growth/next_growth` 同样只从已获准返回的枚举生成，不递归解释任意`status`，不为展示追加读取。ID-only、未知值、匿名数或未授权资料不猜级数；明确审核拦截不代表用户写错，不自动改写或重试。网页自己的周/月Agent统计只供网页会话读取，不是CLI/MCP新增能力。
+
+`context` 仍取工作台和简报，不是后续完整续接接口。一部分403而另一部分可读时，返回可读内容、`partial=true`与缺失说明，退出0；两部分403退出4。401、网络、429、5xx或非法响应仍整体失败，不输出已读部分掩盖故障。成功子结果内部也可能有 `missing_sections`，必须继续检查。
+
+每条缺失说明当前固定为 `section/required_capability/reason` 三字段，例如：
+
+```json
+{"section":"briefing","required_capability":"read_notifications","reason":"capability_disabled"}
+```
+
+后端明确判定开关关闭才使用 `capability_disabled`；一般403不猜测具体原因，也不输出任意上游错误正文。`--human` 单独说明未读到什么，“未读取”不能解释为“没有资料”。
+
+成功写入和幂等回放在读取权限关闭时可能只有资源ID、write_status及审计/审核信息和missing_sections。机器JSON保留结果，human解释“写入成功，内容未返回”，不要因为少了内容字段而重试；202、audit_pending或提交未知不改成无条件完成。重名409读取受限时不带已有ID/title，只说明同名已存在且无权显示详情；仍是冲突，不是成功。
+
+知识草稿需要read_drafts+read_knowledge，项目草稿需要read_drafts+read_projects。草稿聚合与项目列表/详情/工作台/关联/简报都按组合处理，混合结果标缺口；既定project_count/knowledge_count/draft_count不变。可确认的自有项目草稿证据也遮自由文本；未知/非自有来源不靠文字猜测分类。r3补修仍在验收：写入前是受限草稿时，即使本次改成非草稿，也不能通过回执带出未提供的原内容。
+
+关闭读取知识后，项目详情、工作台、简报不返回受限知识；关闭读取草稿后，知识列表/搜索/单卡详情/项目关联/工作台/简报不返回草稿，混合列表先过滤再分页。关闭读取项目后，工作台不返回最近项目内容，数量等允许的汇总仍保留；简报project_update和草稿列表的整条项目草稿也被过滤，不只遮标题，其他草稿照常。分页/by_kind不计算被排除项目，missing_sections说明缺口；开关账号级。通知摘要仍仅调查，不称全部内容路径均封闭。
+
+项目或项目进展来源的知识证据在关闭读取项目时隐藏自由文本（摘要、来源标题、摘录、URL、文件键），保留ID/类型/时间和条数并标明缺口。项目详情和简报中的`knowledge_applied`事件，在读取知识或读取草稿关闭时正文隐藏，事件本身、分页和计数保留；不能把空正文解释成没有发生事件。调用方自写的pending summary仍按原合同，不混为项目证据。
+
+专门调用`drafts`而无读取草稿权限返回403；知识列表显式请求draft而无该权限也返回403。混合或聚合结果仍有可读部分时，则返回可读内容和`missing_sections`；受限草稿详情404保持不可探知。403与缺口元数据并存取决于整个请求还是其中一部分受限，不是相互替代。
+
+简报游标已经推进或进入分页窗口后，不保证重开权限会补发被跨过的事件。若没有正在翻页的窗口，且新窗口里全部事件都被权限过滤、没有其他可见事件，游标保持原样，重开后这些旧事件可能再次出现；空的续页仍可能推进窗口。不要承诺一律补发、一律不补发或一律空页不推进。恢复权限后主动重读列表/详情，不只等下一条简报。后端知识筛选拒绝非法或显式空白长势，合法/省略不变；CLI保留本地校验，MCP保留显式空status并如实返回固定校验原因。
+
+写入输入的最小示例，内容应由用户明确提供或确认，不由命令行生成摘要：
+
+写入前先读本命令的 `--help` 和技能安全示例，不猜字段：例如 `caotang --agent "Codex" project create --help`、`caotang --agent "Codex" knowledge add --help`、`caotang --agent "Codex" source add --help`、`caotang --agent "Codex" progress add --help`。需要 JSON 的写命令支持 `--input -` 以标准输入传对象；错误中的 `missing_fields/unknown_fields/invalid_fields` 用来核对字段，不自动凑值或重发未知结果。
+
+`intent` 必填；用户没说用途时按其原话拟一句，保存前告知这句用途待确认，用户可以改；确认保存的内容包括它，未明确同意不写。`caotang --agent "Codex" knowledge` 不带参数是列表；按名称找项目用 `search`，没有 `projects --q`。
+
+```json
+{"title":"学习记录","intent":"核对做法","summary":"自己分析后的摘要","source_type":"manual"}
+```
+
+上例用于knowledge add；project create必填title、summary，最少为 `{"title":"项目名称","summary":"项目说明"}`，标题2–80码点，简介非空且最多280码点。记录一件事完成了，用 `progress add`，示例 `{"body":"明确的进展"}`；`visibility` 省略时实际保存为私有，也可显式传private，不能传public。
+source add可用 `{"source_type":"external_url","source_url":"https://example.com"}`，`source_title` 选填；stage set只传 `{"stage":"当前阶段"}`。
+只读不能写或发起写类待确认，读写仍与当前账号能力取交集。没有删除、归档、公开可见性直改命令，既有网页确认线不变。
+PDF仅检查边界/文件头并转交原始字节，不解析全文。流程只有一次grant、一次Go网关PUT，匹配stored receipt后才挂来源；未知结果不重PUT、不换grant。
+任何写入/429/503/审计补录都不自动重执业务；公开发布失败可能保留私有候选，应先在网页核查。
+
+## 范围与限制
+
+CLI 负责在本人授权范围内读写草堂数据，不提供内置大模型，不抓取或解析来源全文，不自动写入、重试、公开或执行删除。日历、日程等后续功能不属于此版本的命令范围。
+
+`version` 只说明本机包版本，不表示远端服务或 npm registry 的发布状态。`update` 只输出手动更新命令，不查询 registry、不下载或自动安装；由本人决定是否执行。生产部署和 npm 发布仍是独立的维护操作。
+
+本地凭据安全依赖 POSIX 属主、权限和链接检查，不是同一用户下进程之间的强隔离；Windows 文件权限尚未完成验收。安装成功也不代表 AI 已加载全部技能或完成业务操作，应以实际连接、权限和业务回执为准。

package/bin/caotang.cjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+"use strict";
+
+const major = Number(process.versions.node.split(".")[0]);
+if (!Number.isInteger(major) || major < 20) {
+  process.stderr.write(JSON.stringify({ code: "node_version_unsupported", message: "需要 Node.js 20 或更新版本。", next_action: "请安装官方支持的 Node.js LTS 后重试。" }) + "\n");
+  process.exitCode = 2;
+} else {
+  const controller = new AbortController();
+  process.once("SIGINT", () => controller.abort());
+  import("../dist/cli.js").then(({ runCLI }) => runCLI(process.argv.slice(2), { signal: controller.signal })).then((code) => { process.exitCode = code; }).catch(() => {
+    process.stderr.write(JSON.stringify({ code: "cli_unavailable", message: "命令行暂不可用。", next_action: "请检查本地开发构建，不要重复业务写入。" }) + "\n");
+    process.exitCode = 7;
+  });
+}

package/dist/agent-identity.js

@@ -0,0 +1,14 @@
+import { createHash } from "node:crypto";
+import { CliError } from "./errors.js";
+export function agentIdentity(value) {
+    if (typeof value !== "string")
+        throw new CliError("agent_name_required", "请用你自己的名字再运行 setup --agent <你的名字>。", "之后每条命令都带同一个 --agent <你的名字>；不会借用其他 AI 的连接。");
+    const name = value.trim();
+    if ([...name].length < 1 || [...name].length > 80 || Buffer.from(name, "utf8").toString("utf8") !== name || /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(value) || /[^\S ]/u.test(name))
+        throw new CliError("invalid_agent_name", "AI 名字须为1至80个可显示字符。", "请去掉控制字符，使用自己的简短名字并在后续命令保持一致。");
+    const key = name.replace(/ /g, "").toLowerCase();
+    const platforms = { claudecode: "claude-code", "claude-code": "claude-code", codex: "codex", openclaw: "openclaw", kimicode: "kimi-code", "kimi-code": "kimi-code", "kimi工作模式": "kimi-work", kimiwork: "kimi-work", "kimi-work": "kimi-work", workbuddy: "workbuddy" };
+    return { name, key, fileKey: createHash("sha256").update(key, "utf8").digest("hex"), ...(Object.hasOwn(platforms, key) ? { platform: platforms[key] } : {}) };
+}
+// POSIX shell words: never interpolate a free-form name in double quotes.
+export const shellWord = (value) => "'" + value.replace(/'/g, "'\"'\"'") + "'";