@kyo-so/cli 0.8.0 → 0.9.1

package/README.zh-CN.md

@@ -36,6 +36,45 @@ Kyoso 不会应用代码更改。
 
 无需全局安装。通过 `npx` 或 `bunx` 运行 Kyoso。
 
+### 集成模式
+
+| 模式               | 安装内容             | MCP | 客户端             |
+| ------------------ | -------------------- | --: | ------------------ |
+| Marketplace Plugin | Skill＋本地stdio MCP |  有 | Codex／Claude Code |
+| CLI＋Skill-only    | npm CLI＋Skill       |  无 | Codex／Claude Code |
+| 手动setup          | 手动MCP注册＋Skill   |  有 | Codex／Claude Code |
+
+拿不准时请选择Marketplace Plugin：两条命令即可同时安装Skill和MCP server。步骤见下方的[Codex](#codex)／[Claude Code](#claude-code)小节。
+
+#### Marketplace Plugin
+
+Plugin包含Skill和pin到已发布Kyoso CLI精确版本的MCP定义，但不包含CLI本体。MCP首次启动需要访问npm网络。已缓存的package可能可以offline启动，但不作保证。manifest中的`Read` capability仅是显示metadata，不会授予额外filesystem权限。
+
+Plugin中的Skill将内置的`kyoso` MCP server声明为dependency，因此显式Kyoso review会通过MCP而不是CLI fallback。如果禁用内置Plugin MCP，应将Plugin Skill视为不可用：重新启用MCP，或移除Plugin并改用CLI＋Skill-only。Plugin不是CLI fallback mode。
+
+#### CLI＋Skill-only
+
+```bash
+# Global CLI＋Codex Skill
+npm install -g @kyo-so/cli
+kyoso setup codex --write --skill-only --global
+
+# Project CLI＋Codex Skill
+npm install -D @kyo-so/cli
+npx kyoso setup codex --write --skill-only
+```
+
+Claude Code请将`codex`替换为`claude-code`。默认仍为dry-run。`--skill-only`不会读写MCP配置，也不能与`--runner`／`--command`组合使用。
+
+Skill-only有意不声明MCP dependency。当它到达`npx`或`bunx`的package-runner fallback时，Codex Auto mode可能要求sandbox network escalation approval；在PATH上安装`kyoso`可以避免该fallback。
+
+#### 迁移
+
+- 从手动MCP迁移到CLI＋Skill：先安装CLI和Skill，再运行`codex mcp remove kyoso`或`claude mcp remove kyoso --scope local|project|user`。
+- 从CLI＋Skill迁移到Plugin：添加Plugin并确认enabled后，再删除手动MCP注册。手动复制的Skill不会自动删除。
+- 从Plugin迁移到CLI＋Skill：先安装CLI和Skill，再运行`codex plugin remove kyoso@kyoso`。
+- 从CLI＋Skill恢复到手动MCP：运行`kyoso setup codex --write`或`kyoso setup claude-code --write`。
+
 ### Claude Only / Codex Only
 
 Kyoso 可以在只有 Claude 或只有 Codex 可用时运行。请在 `kyoso.toml` 中禁用缺失的 backend；示例见 `examples/claude-only.toml` 和 `examples/codex-only.toml`。
@@ -54,21 +93,32 @@ claude setup-token
 
 设置该命令得到的 `CLAUDE_CODE_OAUTH_TOKEN`，或设置 `ANTHROPIC_API_KEY` 以使用 direct API billing。
 
-2. 注册 MCP 并安装 review skill。
+2. 安装 Marketplace Plugin(推荐)。
+
+```text
+/plugin marketplace add hokupod/kyoso
+/plugin install kyoso@kyoso
+```
+
+Plugin 会安装 Kyoso review Skill 和 pin 到已发布 CLI version 的本地 stdio MCP server。通过 Plugin 安装时，无需运行 `kyoso setup claude-code`。
+
+3. 或者，注册 MCP 并安装 review skill。
 
 ```bash
 npx @kyo-so/cli setup claude-code --write
 bunx @kyo-so/cli setup claude-code --write
 ```
 
-3. 验证 setup。
+需要手动注册 MCP 时，请使用 `examples/claude-code-mcp.json`。
+
+4. 验证 setup。
 
 ```bash
 npx @kyo-so/cli doctor
 bunx @kyo-so/cli doctor
 ```
 
-4. 从 Claude Code 请求 review。
+5. 从 Claude Code 请求 review。
 
 ```text
 Use Kyoso plan_review on this plan before implementation.
@@ -82,21 +132,56 @@ Use Kyoso plan_review on this plan before implementation.
 codex login
 ```
 
-2. 注册 MCP 并安装 review skill。
+2. 安装 Marketplace Plugin(推荐)。
+
+```bash
+codex plugin marketplace add hokupod/kyoso
+codex plugin add kyoso@kyoso
+```
+
+也可以在Codex desktop的Plugins page或`/plugins`中选择Kyoso。若新添加的Marketplace未显示，请refresh／restart desktop app。使用`codex plugin list --marketplace kyoso --json`确认安装，使用`codex plugin remove kyoso@kyoso`删除Plugin。通过 Plugin 安装时，无需运行 `kyoso setup codex`。
+
+在Codex Auto mode中，需要approval的Kyoso tool调用可能会被拒绝。若要仅为个人账户预先批准，请将以下设置添加到`~/.codex/config.toml`（若已设置`CODEX_HOME`，则为`$CODEX_HOME/config.toml`）。**只有在你信任Kyoso，并接受所选代码与review context可能发送给已配置的外部model provider时，才应启用此设置。** Plugin默认不会启用它。
+
+```toml
+[plugins."kyoso@kyoso".mcp_servers.kyoso.tools.diff_review]
+approval_mode = "approve"
+
+[plugins."kyoso@kyoso".mcp_servers.kyoso.tools.plan_review]
+approval_mode = "approve"
+
+[plugins."kyoso@kyoso".mcp_servers.kyoso.tools.security_review]
+approval_mode = "approve"
+```
+
+如果Kyoso不是通过Plugin、而是直接注册为MCP server（`kyoso setup codex --write` 或手动设置），请使用不带 `plugins."kyoso@kyoso".` 前缀的 `mcp_servers.kyoso` 键：
+
+```toml
+[mcp_servers.kyoso.tools.diff_review]
+approval_mode = "approve"
+
+[mcp_servers.kyoso.tools.plan_review]
+approval_mode = "approve"
+
+[mcp_servers.kyoso.tools.security_review]
+approval_mode = "approve"
+```
+
+3. 或者，注册 MCP 并安装 review skill。
 
 ```bash
 npx @kyo-so/cli setup codex --write
 bunx @kyo-so/cli setup codex --write
 ```
 
-3. 验证 setup。
+4. 验证 setup。
 
 ```bash
 npx @kyo-so/cli doctor
 bunx @kyo-so/cli doctor
 ```
 
-4. 从 Codex 请求 review。
+5. 从 Codex 请求 review。
 
 ```text
 Use Kyoso diff_review on the current diff. I need a second opinion before merging.
@@ -141,6 +226,8 @@ kyoso doctor
 kyoso init
 kyoso setup codex
 kyoso setup claude-code
+kyoso setup codex --write --skill-only
+kyoso setup claude-code --write --skill-only
 ```
 
 ## Usage Examples
@@ -203,11 +290,13 @@ MCP stdout 专用于 protocol messages。Logs 会写到 stderr 或 local audit t
 
 内置的 `kyoso-review` skill 有意保持范围很窄。只有当你明确请求 Kyoso、multi-agent review、plan review、security review、CISA Secure by Design review 或 diff review 时，才应触发它。
 
-当 Kyoso MCP tools 可用时，skill 会优先使用它们。如果尚未注册 MCP server，skill 会按照文档中的 CLI fallback，通过 `npx -y @kyo-so/cli` 或 `bunx @kyo-so/cli` 获取 JSON output。
+Skill使用第一个可用路径，顺序是Kyoso MCP tools、PATH上已安装的`kyoso`、`npx -y @kyo-so/cli`、`bunx @kyo-so/cli`。package runner fallback可能需要network access，也可能发生version drift，因此MCP-less正常路径应使用已安装CLI。
+
+`kyoso setup codex --write --skill-only`默认将canonical Skill directory复制到`.agents/skills/kyoso-review/`。添加`--global`后复制到`~/.agents/skills/kyoso-review/`。
 
-`npx @kyo-so/cli setup codex --write` 和 `bunx @kyo-so/cli setup codex --write` 默认将其复制到 `.agents/skills/kyoso-review/`。添加 `--global` 会复制到 `~/.agents/skills/kyoso-review/`。
+`kyoso setup claude-code --write --skill-only`默认复制到`.claude/skills/kyoso-review/`。添加`--global`后复制到`~/.claude/skills/kyoso-review/`。
 
-`npx @kyo-so/cli setup claude-code --write` 和 `bunx @kyo-so/cli setup claude-code --write` 默认将其复制到 `.claude/skills/kyoso-review/`。添加 `--global` 会复制到 `~/.claude/skills/kyoso-review/`。
+managed install会把canonical directory digest和CLI version记录到`.kyoso-install.json`。当前或已知historical copy会被adopt并自动更新；修改过或未知的copy会报告conflict并保持不变。`--force`只替换该Skill directory，不会删除或覆盖MCP配置。
 
 ## Safety Model
 
@@ -221,6 +310,10 @@ Repository content、plans、diffs 和 selected files 在 backend prompts 中被
 
 Finding title 会为 aggregation 规范化为简洁英文；evidence、recommendations 和 summaries 可以继续使用用户的语言。
 
+Audit trace 写入受信任的 user state root，而不是由 workspace 控制的 path。在受支持的 POSIX runtime 上，Kyoso 会在可用时使用 absolute `$XDG_STATE_HOME`，否则使用 `$HOME/.local/state`；只有 owner、permission、containment 和 symlink 检查均成功时才会写入。验证或 safe open 失败时，它不会静默 fallback 到其他 location：会为该 review fail-close 禁用 Audit 写入，返回 sanitized warning，并继续 review。
+
+Windows，以及无法证明所需 filesystem capability 的环境，会 fail-close 禁用 Audit 写入。能够修改 trusted state root 或 rename 已验证 inode 的 same OS user hostile process 不在此保证范围内；防御该威胁需要 OS sandbox 或 native dirfd-based support。
+
 ## Agent Auth
 
 可用时，Codex 使用 local `codex` login。默认 subscription-backed path 不需要 API key。
@@ -266,15 +359,15 @@ effort 的工作方式不同：Kyoso 不会为它设置 env var，而是在每
 
 ## Audit
 
-Audit traces 写入：
+在受支持的 POSIX runtime 上，Audit traces 会写入 user state base（absolute `$XDG_STATE_HOME`，否则 `$HOME/.local/state`）下：
 
 ```text
-.kyoso/traces/<yyyy-mm-dd>/<traceId>.jsonl
+<state-base>/kyoso/workspaces/<sha256(realpath(cwd))>/<logical audit.directory>/<yyyy-mm-dd>/<traceId>.jsonl
 ```
 
-Raw agent output 和 raw file contents 默认禁用。
+`audit.directory`是 logical relative directory（默认：`.kyoso/traces`），不是 workspace 内的 directory。现有 workspace `.kyoso/traces`不会被自动迁移或删除。
 
-不要将 `.kyoso/traces/` 提交到 Git。`kyoso init` 会把 `.kyoso/` 添加到 `.gitignore`，本 repository 也同样如此。如果启用 `audit.includeRawAgentOutput`，traces 可能会保留 sensitive review output；请按照 local retention policy 定期删除旧 traces。
+Raw agent output 和 raw file contents 默认禁用。如果启用 `audit.includeRawAgentOutput`，traces 可能会保留 sensitive review output；请按照 local retention policy 删除旧 traces。在 Windows 或无法证明安全 filesystem capability 的环境中，Audit trace 写入会保持禁用，review 会返回 sanitized warning。
 
 ## Config
 

package/dist/audit/safeTraceFile.d.ts

@@ -0,0 +1,20 @@
+import type { FileHandle } from "node:fs/promises";
+export declare const AUDIT_WARNING_UNSUPPORTED_OPEN_CAPABILITY = "AUDIT_DISABLED_UNSUPPORTED_CAPABILITY: Audit trace writing requires unavailable filesystem capabilities.";
+export type AuditOpenConstants = Partial<Record<"O_CREAT" | "O_EXCL" | "O_APPEND" | "O_WRONLY" | "O_NOFOLLOW" | "O_NONBLOCK", number>>;
+export type OpenVerifiedTraceFileOptions = {
+    kyosoRoot: string;
+    workspaceHash: string;
+    logicalDirectory: string;
+    date: string;
+    traceId: string;
+    uid: number;
+    workspaceRoot: string;
+    openConstants?: AuditOpenConstants;
+    beforeOpen?: (tracePath: string) => Promise<void> | void;
+};
+export type OpenedTraceFile = {
+    handle: FileHandle;
+    tracePath: string;
+};
+export declare function openVerifiedTraceFile(options: OpenVerifiedTraceFileOptions): Promise<OpenedTraceFile>;
+export declare function secureOpenFlags(provided?: AuditOpenConstants): number | undefined;

package/dist/audit/stateRoot.d.ts

@@ -0,0 +1,38 @@
+export declare const AUDIT_WARNING_DIRECTORY_IGNORED = "AUDIT_DIRECTORY_IGNORED: Audit directory is invalid; using the default logical directory.";
+export declare const AUDIT_WARNING_UNSUPPORTED_PLATFORM = "AUDIT_DISABLED_UNSUPPORTED_PLATFORM: Audit trace writing is unavailable on this platform.";
+export declare const AUDIT_WARNING_UNSUPPORTED_CAPABILITY = "AUDIT_DISABLED_UNSUPPORTED_CAPABILITY: Audit trace writing requires unavailable filesystem capabilities.";
+export declare const AUDIT_WARNING_UNSAFE_STATE_ROOT = "AUDIT_DISABLED_UNSAFE_STATE_ROOT: Audit state root could not be verified.";
+export type AuditRuntimeOptions = {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    getuid?: () => number | undefined;
+};
+export type ResolvedAuditStateRoot = {
+    stateBase: string;
+    kyosoRoot: string;
+    workspaceRoot: string;
+    workspaceHash: string;
+    logicalDirectory: string;
+    uid: number;
+    warnings: string[];
+};
+export type AuditStateRootResolution = ResolvedAuditStateRoot | {
+    warnings: string[];
+};
+export type AuditStateRootCapability = {
+    available: boolean;
+};
+export declare function resolveAuditStateRoot(options: {
+    cwd: string;
+    directory: string;
+} & AuditRuntimeOptions): Promise<AuditStateRootResolution>;
+export declare function inspectAuditStateRootCapability(options: {
+    cwd: string;
+} & AuditRuntimeOptions): Promise<AuditStateRootCapability>;
+export declare function ensureTrustedDirectory(options: {
+    root: string;
+    segments: string[];
+    uid: number;
+    workspaceRoot?: string;
+}): Promise<string>;
+export declare function isResolvedAuditStateRoot(resolution: AuditStateRootResolution): resolution is ResolvedAuditStateRoot;

package/dist/audit/trace.d.ts

@@ -1,12 +1,24 @@
+import type { FileHandle } from "node:fs/promises";
+import { type AuditRuntimeOptions } from "./stateRoot.js";
+import { type AuditOpenConstants } from "./safeTraceFile.js";
+export declare const AUDIT_WARNING_WRITE_FAILED = "AUDIT_WRITE_FAILED: Audit trace writing failed; no further audit events will be written.";
+export declare const AUDIT_WARNING_FINALIZE_FAILED = "AUDIT_FINALIZE_FAILED: Audit trace close failed.";
+export declare const AUDIT_WARNING_WRITE_AFTER_FINALIZE = "AUDIT_WRITE_AFTER_FINALIZE: Audit trace is already finalized.";
 export type TraceWriter = {
-    tracePath?: string;
+    readonly tracePath?: string;
     warnings: string[];
     write(event: Record<string, unknown>): Promise<void>;
+    finalize(): Promise<void>;
 };
-export declare function createTraceWriter(options: {
+export type TraceWriterOptions = {
     enabled: boolean;
     directory: string;
     traceId: string;
     cwd: string;
     includeRawAgentOutput?: boolean;
-}): TraceWriter;
+    openConstants?: AuditOpenConstants;
+    beforeOpen?: (tracePath: string) => Promise<void> | void;
+    closeHandle?: (handle: FileHandle) => Promise<void>;
+    writeChunk?: (handle: FileHandle, buffer: Buffer, offset: number) => Promise<number>;
+} & AuditRuntimeOptions;
+export declare function createTraceWriter(options: TraceWriterOptions): TraceWriter;