@twinklerg/coden 0.1.5 → 0.1.7

package/README.md

@@ -10,7 +10,7 @@ CodeN（Code NJU）是一个用 TypeScript 独立实现的极简编程智能体
 
 ```bash
 bun add -g @twinklerg/coden     # 或 npm install -g @twinklerg/coden
-coden --version                 # 0.1.5
+coden --version                 # 0.1.6
 coden --help
 ```
 
@@ -34,6 +34,7 @@ just check
 export CODEN_OPENAI_API_KEY=...
 coden "修复当前项目的测试失败"
 coden -p --auto "实现功能并运行测试"
+coden --smart-approve "实现功能并运行测试"
 
 export CODEN_ANTHROPIC_API_KEY=...
 coden --provider anthropic --model claude-sonnet-4-20250514
@@ -44,9 +45,9 @@ coden --resume                   # 列出当前工作区的会话
 
 无 prompt 时进入 REPL。交互式 REPL 支持完整多行编辑：Enter 提交；终端可区分该按键时，Shift+Enter 插入换行；所有终端均可在行尾输入单个 `\` 后按 Enter 继续下一行（`\\` 表示保留一个字面反斜杠）。支持多行粘贴、跨行方向键编辑和当前进程内输入历史。传统终端若无法区分 Shift+Enter，请使用行尾 `\`。
 
-支持 `/help`、`/session`、`/sessions`、`/compact`、`/reload`、`/new` 和 `/quit`。启动横幅会显示当前版本与 16 位 workspace hash。
+支持 `/help`、`/skills`、`/session`、`/sessions`、`/compact`、`/reload`、`/new` 和 `/quit`。启动横幅会显示当前版本与 16 位 workspace hash。
 
-核心选项：`--provider`、`--model`、`-p/--print`、`--resume [session-id]`、`--auto`、`--verbose`、`--max-steps`、可重复的 `--plugin` 和 `--version`。
+核心选项：`--provider`、`--model`、`-p/--print`、`--resume [session-id]`、`--smart-approve`、`--auto`、`--allow-outside-workspace`、`--verbose`、`--max-steps`、可重复的 `--plugin` 和 `--version`。
 
 ## 配置
 
@@ -56,6 +57,8 @@ coden --resume                   # 列出当前工作区的会话
 {
   "provider": "openai",
   "model": "gpt-5-mini",
+  "approvalModel": "gpt-5-mini",
+  "approvalStrictness": "medium",
   "maxSteps": 20,
   "contextWindow": 128000,
   "reservedOutputTokens": 8192,
@@ -71,13 +74,57 @@ coden --resume                   # 列出当前工作区的会话
 
 `env` 字段（用户级与项目级均可）声明环境变量（含敏感密钥），加载配置时注入进程环境，无需手动 `export`。两级 `env` 合并时**项目级逐键覆盖用户级**；注入**不覆盖** `shell` 中已导出的同名变量（CLI > 环境变量 > 配置 env）。密钥请放 `~/.config/coden/` 或 `.coden/`（已被 `gitignore` 忽略、默认不入库），不要放进会被提交、共享或分发的目录。
 
+`approvalModel` 使用与任务相同的 provider 和凭据，未设置时回退到 `model`。`approvalStrictness` 只能是 `soft`、`medium` 或 `hard`，默认 `medium`。
+
 会话和 trace 位于 `$XDG_DATA_HOME/coden/sessions/<workspace-hash>/`（默认 `~/.local/share/coden`）。
 
+## Agent Skills
+
+CodeN 兼容 [Agent Skills](https://agentskills.io/specification) 的渐进式披露格式。启动时扫描以下目录的直接子目录；每个候选项必须为 `<skill-name>/SKILL.md`：
+
+```text
+~/.agents/skills/<skill-name>/SKILL.md
+<workspace>/skills/<skill-name>/SKILL.md
+<workspace>/.agents/skills/<skill-name>/SKILL.md
+```
+
+其中 `skills/` 用于仓库随附、可公开分发的 Skill，`.agents/skills/` 用于本地安装的项目级 Skill。同名条目按上述顺序覆盖，因此本地安装的项目级 Skill 优先级最高。
+
+项目级 Skill 覆盖同名用户级 Skill。`SKILL.md` 使用 YAML frontmatter，最小内容如下：
+
+```markdown
+---
+name: pdf-processing
+description: Use when reading or modifying PDF documents.
+---
+
+# PDF workflow
+
+Read the relevant files before changing them.
+```
+
+启动上下文只包含有效 Skill 的名称和描述，不会注入完整正文。任务匹配时，模型调用只接受名称的 `activate_skill` 加载完整说明和 Skill 绝对根目录；引用的 `references/`、`scripts/` 等资源仍按需使用普通工具读取。`/skills` 不调用模型，按名称列出当前生效的名称、描述和 `project`/`user` 来源。Skill 仅在启动时发现，文件变更需重启后生效。无效、超限或通过符号链接逃逸扫描根目录的条目会被跳过；`--verbose` 显示原因。
+
+仓库提供 [`coden-tool-plugin-development`](skills/coden-tool-plugin-development/SKILL.md) Skill，用于指导兼容 Agent Skills 的编程智能体创建、修改和测试本地 TypeScript 或 npm 分发的 CodeN 工具插件，并完成发布前验证。可从本仓库安装指定 Skill：
+
+```bash
+npx skills add TwinklerG/CodeN --skill coden-tool-plugin-development
+```
+
 ## 工具与权限
 
-默认且仅默认暴露四个工具：`read`、`write`、`edit` 和 `bash`。文件工具拒绝工作区外路径及符号链接逃逸。默认模式自动执行读取，修改需确认，递归删除、`sudo`、破坏性 Git 等高风险命令每次确认。`--auto` 跳过确认，但仍进行 Schema 校验和文件工作区检查。
+默认提供 `read`、`write`、`edit`、`bash` 和只读的 `activate_skill`；没有有效 Skill 时，激活工具会返回 `skill.not_found`。结构化文件工具按最终真实路径（新文件按最近存在的真实父目录）分类，避免符号链接绕过：
+
+| 模式 | 工作区内 `read`/`write`/`edit` | 工作区外 `read`/`write`/`edit` |
+| --- | --- | --- |
+| 默认交互模式 | `read` 自动允许；`write`/`edit` 人工确认 | 作为修改操作请求逐次或会话授权 |
+| `--smart-approve` | `read` 自动允许；普通 `write`/`edit` 逐次由独立 LLM 审查，不确定时人工确认 | 直接人工确认 |
+| `--auto` | 自动允许 | 返回 `permission.outside_workspace_denied` |
+| `--auto --allow-outside-workspace` | 自动允许 | 自动允许 |
+
+`--allow-outside-workspace` 只能与 `--auto` 一起使用，并且**只**控制 `read`、`write`、`edit`。它会允许修改当前工作区之外的任意文本文件，应仅在明确需要时使用。`activate_skill` 仅自动读取已发现且重新验证过的入口 `SKILL.md`；使用普通 `read` 访问用户级 Skill 的附属资源仍适用表中的外部路径规则。
 
-**这不是通用安全沙箱。** `bash` 和 TypeScript 插件拥有当前用户进程权限；风险分类是防误操作的启发式护栏。Bash 超时会终止其进程组；主进程内的插件只能通过 `AbortSignal` 协作取消，忽略信号的可信插件可能在超时结果返回后继续运行。
+**这不是通用安全沙箱。** `bash` 不受结构化文件路径开关约束，仍以工作区作为当前目录但可以访问外部路径；`bash` 和 TypeScript 插件拥有当前用户进程权限。风险分类是防误操作的启发式护栏。Bash 超时会终止其进程组；主进程内的插件只能通过 `AbortSignal` 协作取消，忽略信号的可信插件可能在超时结果返回后继续运行。
 
 ## 本地 TypeScript 插件
 
@@ -87,7 +134,7 @@ CodeN 扫描：
 - `<workspace>/.coden/plugins/*.ts`
 - `--plugin` 或配置中的附加目录
 
-项目插件首次加载需信任确认（`--auto` 跳过）。插件应避免模块顶层副作用；`/reload` 基于内容哈希重建模块并原子替换 Registry（内容未变的插件复用已加载模块）。
+项目插件首次加载始终需人工信任确认；`--auto` 只跳过工具调用确认，不会跳过工作区插件信任。智能审批对每次普通工作区内修改独立审查；危险、工作区外、无效输出、超时或模型故障都转人工，且没有输入时失败关闭。LLM 审批不是沙箱。插件应避免模块顶层副作用；`/reload` 基于内容哈希重建模块并原子替换 Registry（内容未变的插件复用已加载模块）。
 
 **插件必须是自包含单文件**：Bun 的模块缓存按真实路径去重且忽略查询参数，因此 CodeN 通过 `data:text/typescript` URL 加载插件源码以保证重载生效——相对路径导入（`./helper.ts`）无法解析，npm 包导入（`import pc from "picocolors"`）正常工作。