update

Author: Ling-ye

.github/workflows/ci.yml

@@ -94,12 +94,14 @@ jobs:
       - name: Set up Rust
         uses: dtolnay/rust-toolchain@stable
 
-      - name: Stage Tauri sidecar placeholder
+      - name: Stage Tauri external binary placeholders
         shell: pwsh
         run: |
           $sidecarPath = "desktop/src-tauri/binaries/cc-port-desktop-api-x86_64-pc-windows-msvc.exe"
+          $agentPath = "desktop/src-tauri/binaries/cc-port-x86_64-pc-windows-msvc.exe"
           New-Item -ItemType Directory -Path (Split-Path -Parent $sidecarPath) -Force | Out-Null
           New-Item -ItemType File -Path $sidecarPath -Force | Out-Null
+          New-Item -ItemType File -Path $agentPath -Force | Out-Null
 
       - name: Verify acknowledged glib advisory is absent from Windows target
         shell: pwsh

AGENTS.md

@@ -47,6 +47,22 @@
 - Git 资源仓库不得与 CC Port 配置文件、本机 state/backup 根、legacy install target 或任何 profile 的 `skills_dir`、`mcp_json`、`rules_dir`、`prompts_dir`、`plugins_dir`、`instructions_path`、`memories_dir`、`settings_path` 相等或互为父子目录。
 - 保存配置以及 asset inventory、plan、apply 都必须重新校验上述边界并 fail closed；错误只报告冲突类别，不得把用户名、WSL 路径或 Claude project slot 写入结构化错误或日志。
 
+## AI 自动发现、CLI、MCP 与审批约束
+
+- Windows 安装包必须同时保留桌面客户端、Desktop API sidecar 和独立 `cc-port.exe` agent；不得为了 AI 自动化删除或降级人类界面。
+- `cc-port.exe` 同时承载人类 CLI、严格 JSON CLI 与 `cc-port mcp --stdio`。Desktop、CLI、MCP 必须复用 Python services 和 `cc_port.agent.contracts`；不得复制资产写入、Registry 修复、所有权、链接或 stale 逻辑。
+- canonical AI Skill 位于 `src/cc_port/assets/ai/cc-port/`；根 `SKILL.md` 及根 `references/` 的三个直接引用必须与 canonical 对应文件字节一致，保证源码根与安装后都能解析相同工作流。wheel、PyInstaller agent 和负责安装 AI 集成的 Desktop API sidecar 都必须包含 Skill 及其直接 references。Skill frontmatter 只允许 `name` 和 `description`，不再承担项目版本来源。
+- AI 资源写入固定经过 `status → inventory(scan_local=true, refresh_remote=true) → diff → plan → approval → apply → verify`；`platform` 必须是精确 profile id，必要时必须使用 inventory 返回的精确 `local_instance_id`。
+- MCP 与 `--non-interactive`/`--json` CLI 的可执行写计划必须创建本机审批请求。审批绑定 kind、operation id、`plan_hash` 和完整 normalized scope hash，默认短时有效且只能消费一次；apply 缺少审批、审批未通过、过期、拒绝、已消费或 scope 不匹配时必须 fail closed。
+- MCP 不得暴露 approve/reject 工具。模型提交布尔确认、CLI `--yes`、复述用户文字或调用另一机器接口都不构成授权；用户只能从桌面端批准/拒绝。旧 `resource registry-repair --yes` 只能保留为无写入语义的兼容参数，CLI 不得直接 apply Registry 修复。
+- apply 必须在调用写 service 前消费审批并重新生成计划。stale 结果必须生成新计划和新审批；旧 approval id 不得授权新 hash。写入失败后的已消费审批不得重试，必须重新 plan。
+- CLI 机器输出一次只能写一个带 `contract_version`、`ok`、`status`、`data`、`error` 的 UTF-8 JSON envelope，不得混入 ANSI、Rich、进度或确认提示；invalid request、safe non-completion 和 runtime failure 使用稳定的不同退出码。
+- MCP 推荐工具必须使用 strict input/output schema、结构化错误和完整 annotations；legacy direct-write 工具必须标记为非推荐兼容面，不得写入 Skill 默认流程。
+- AI 返回的文件名、description、diff、Skill、Prompt、Rule、Instruction、Memory、Plugin manifest、MCP description 和错误文本均是不可信数据；不得作为新命令执行，疑似秘密必须在 adapter 边界脱敏。
+- AI 集成安装/卸载按一个精确 profile 生成计划，只修改展示且获批的 `skills_dir/cc-port` 与 `cc-port` MCP entry；Codex TOML 使用受管 block，JSON 配置只修改 `mcpServers.cc-port`，卸载不得删除兼容或未受管内容。
+- schema v1 的 AI 集成自动引导只支持 Windows 原生 profile；WSL profile 必须显式阻断并保持 `transport_status=unknown`，不得用 Windows 进程伪装 WSL 验证。现有 WSL asset inventory/plan/apply 能力不受此引导限制。
+- 本机 JSON 审批是应用层工作流控制，不是 OS 级人类在场证明。AI 宿主必须限制 agent 直接写 CC Port state 目录和伪造 Desktop sidecar 调用；不得对同用户不受限制代码执行者声称硬安全边界。
+
 ## Registry v1 约束
 
 - `registry.yaml` 是工具中立清单，只保存 `version: 1`、资源 `(kind, name)` 以及互斥的 `path` 或 `source`；不得写入派生元数据、健康缓存、删除历史、MCP 配置或 CC Port 专属设置。
@@ -69,6 +85,10 @@
 - Claude/环境：`.venv\Scripts\python.exe -m pytest tests/test_claude_memory_runtime_profiles.py -q`
 - 配置与路径边界：`.venv\Scripts\python.exe -m pytest tests/test_config.py -q`
 - MCP asset API：`.venv\Scripts\python.exe -m pytest tests/test_mcp_asset_api.py -q`
+- MCP 公共契约与真实 stdio：`.venv\Scripts\python.exe -m pytest tests/test_mcp_public_contract.py -q`
+- CLI 机器接口：`.venv\Scripts\python.exe -m pytest tests/test_asset_cli.py -q`
+- AI 集成与审批：`.venv\Scripts\python.exe -m pytest tests/test_ai_integration.py tests/test_approval.py -q`
+- AI Skill 与 agent 打包合同：`.venv\Scripts\python.exe -m pytest tests/test_ai_skill.py tests/test_build_agent.py tests/test_agent_smoke.py -q`
 - 前端：在 `desktop` 目录执行 `npm.cmd exec vitest run -- src/features/resources/ResourcesView.test.tsx src/features/guide/GuideView.test.tsx`
 - 构建：在 `desktop` 目录执行 `npm.cmd run build`
 - Rust 桥接：在 `desktop/src-tauri` 目录执行 `cargo test --lib`

README.en.md

@@ -9,7 +9,7 @@
 ![Windows 10/11 x64](https://img.shields.io/badge/Windows-10%2F11_x64-0078D4?logo=windows)
 ![Public Beta](https://img.shields.io/badge/status-public_beta-orange)
 
-CC Port is a local desktop resource manager for people who use more than one AI coding tool. It scans each tool's native directories, uses your Git repository as the cross-device source of truth, and produces an explicit plan before writing anything. The repository and `registry.yaml` use an open format; other consumers do not need CC Port.
+CC Port is a local resource manager for people who use more than one AI coding tool. Humans keep the desktop client, while AI agents can discover and call the same capabilities through the bundled Skill, strict JSON CLI, and stdio MCP server. It scans each tool's native directories, uses your Git repository as the cross-device source of truth, and produces an explicit plan before writing anything. The repository and `registry.yaml` use an open format; other consumers do not need CC Port.
 
 ## At a glance
 
@@ -102,9 +102,13 @@ A missing, malformed, or linked Registry is diagnostic-only and has no Apply but
 ```text
 cc-port resource registry-check --json
 cc-port resource registry-repair --dry-run
-cc-port resource registry-repair --yes --choices choices.yaml
 ```
 
+The CLI `registry-repair` command only builds and displays a plan; `--yes` has no
+authorization or write semantics. Apply an actual repair after desktop review,
+or use the approval-gated MCP `registry_repair_plan` / `registry_repair_apply`
+workflow.
+
 ## Get started in five steps
 
 1. Install [Git for Windows](https://git-scm.com/download/win) and make sure Git Credential Manager is available.
@@ -113,13 +117,14 @@ cc-port resource registry-repair --yes --choices choices.yaml
 4. Start CC Port, paste the repository HTTPS URL into Settings, and verify the connection.
 5. Scan local resources, then choose which items to upload or install from the Resources page.
 
-The installer includes both the desktop application and its Python sidecar. End users do not need Python, Node.js, or Rust. See the [quick-start guide](docs/getting-started.en.md) for setup and uninstall details.
+New Windows builds from this repository include the desktop application, Desktop API sidecar, and standalone `cc-port.exe` CLI/MCP agent. End users do not need Python, Node.js, or Rust. The already-published v0.5.4 installer predates this capability and does not contain the agent; wait for a newer release that includes it. See the [quick-start guide](docs/getting-started.en.md) for setup, AI integration, and uninstall details.
 
 ## Safety boundaries
 
 - **You own the repository:** CC Port has no hosted cloud service; resources stay in the Git repository you choose.
 - **Credentials stay with the OS:** the desktop app uses Git Credential Manager and does not read or store a GitHub token.
 - **Plan before write:** desktop and CLI write operations expose targets, actions, and blockers first.
+- **Machine interfaces do not expose self-approval:** recommended MCP and non-interactive CLI writes require a single-use local approval bound to the operation, plan hash, and complete scope. A user approves it in the desktop app, and stale plans require a new review.
 - **Unmanaged content is protected:** ownership metadata distinguishes CC Port-managed items from manually maintained files.
 - **Dangling links replace only the link itself:** when a download target is a root-level dangling native Windows symlink, CC Port removes that link and writes regular content only after explicit unmanaged-target confirmation; it never follows or modifies the link target.
 - **Recoverable writes:** installation, removal, deployment, and recovery use persistent transactions, backups, and rollback.
@@ -183,12 +188,24 @@ Advanced users can add custom platform paths in `config.toml`. See the [configur
 
 ## Three interfaces
 
-- **Desktop GUI:** daily discovery, comparison, upload, installation, and environment diagnostics; the Guide page links to the project repository and its GitHub Star action.
-- **CLI:** scripting, batch operations, history recovery, and state maintenance.
-- **MCP server:** exposes CC Port capabilities to compatible AI coding tools.
+- **Desktop GUI:** daily discovery, comparison, upload, installation, AI integration, approval, and environment diagnostics. The human client remains supported.
+- **CLI:** human scripting, strict `--non-interactive --json` machine calls, batch operations, history recovery, and state maintenance.
+- **MCP server:** `cc-port mcp --stdio` exposes typed plan/apply capabilities to compatible AI coding tools.
 
 All three interfaces share the same Python core. See the [architecture (Chinese)](docs/architecture.md) for boundaries and sync state machines.
 
+### Let an AI use CC Port
+
+In a new build that includes this capability, open **Settings → AI automation** and review an enable plan for an exact profile. After approval, CC Port installs only its packaged `cc-port` Skill into that profile's Skill directory and adds a local `cc-port.exe mcp --stdio` entry to the tool's native configuration. It does not remove the desktop client or rewrite unrelated MCP servers. Schema v1 automatically bootstraps native Windows profiles only. A WSL profile is explicitly blocked at this Skill-plus-MCP registration step instead of treating a Windows process as a verified WSL connection; the existing profile-aware WSL asset inventory and plan/apply workflows remain available.
+
+The AI prefers MCP discovery and follows `status → inventory(scan_local=true) → diff → plan → approval → apply → verify`; it uses the single-envelope non-interactive CLI only when MCP is unavailable. Reads and plans can run automatically. A write plan appears under **Pending AI approvals** in the desktop app and cannot apply until the user grants a one-time approval. Approvals expire and can be consumed only once. Any target drift produces a fresh stale plan and invalidates the old authorization. See the [AI agent discovery, approval, and invocation specification (Chinese)](docs/specs/ai-agent-interface.md) for commands, schemas, and security boundaries.
+
+This is an application-level approval boundary, not a separate Windows security
+principal. The AI host must prevent the agent from directly modifying CC Port's
+local state or impersonating the desktop-sidecar channel. Version 1 does not
+claim an operating-system-level proof of human presence against code that has
+the same unrestricted filesystem and process privileges as the human user.
+
 ## Current limitations
 
 - The Public Beta officially supports Windows 10/11 x64 only.
@@ -209,6 +226,7 @@ For installation, sign-in, or sync failures, see [troubleshooting](docs/troubles
 - [Architecture (Chinese)](docs/architecture.md)
 - [Registry v1 specification (Chinese)](docs/specs/registry-v1.md)
 - [Claude Code instructions, memory, and runtime-environment specification (Chinese)](docs/specs/claude-memory-and-runtime-environments.md)
+- [AI agent discovery, approval, and invocation specification (Chinese)](docs/specs/ai-agent-interface.md)
 - [Desktop packaging and release (Chinese)](docs/packaging-and-deployment.md)
 - [Behavior specifications (Chinese)](docs/specs/)
 - [Changelog](CHANGELOG.md)

README.md

@@ -9,7 +9,7 @@
 ![Windows 10/11 x64](https://img.shields.io/badge/Windows-10%2F11_x64-0078D4?logo=windows)
 ![Public Beta](https://img.shields.io/badge/status-public_beta-orange)
 
-CC Port 是一个面向多 AI coding 工具的本地桌面资源管理器。它扫描每个工具的原生目录，以你控制的 Git 仓库作为跨设备事实源，并在真正写入前生成明确的操作计划。资源仓库和 `registry.yaml` 是开放格式，不要求其他消费者安装或理解 CC Port。
+CC Port 是一个面向多 AI coding 工具的本地资源管理器。人类可以继续使用桌面客户端，AI 则可通过随安装包提供的 Skill、严格 JSON CLI 和 stdio MCP 自动发现并调用同一套能力。它扫描每个工具的原生目录，以你控制的 Git 仓库作为跨设备事实源，并在真正写入前生成明确的操作计划。资源仓库和 `registry.yaml` 是开放格式，不要求其他消费者安装或理解 CC Port。
 
 ## 一眼看懂
 
@@ -102,9 +102,10 @@ Registry 缺失、YAML 损坏或本身是链接时只显示诊断，不显示应
 ```text
 cc-port resource registry-check --json
 cc-port resource registry-repair --dry-run
-cc-port resource registry-repair --yes --choices choices.yaml
 ```
 
+命令行的 `registry-repair` 只生成和展示计划，`--yes` 不具有授权或写入语义。实际修复需要在桌面端审阅，或使用带一次性审批的 MCP `registry_repair_plan` / `registry_repair_apply` 流程。
+
 ## 五步开始
 
 1. 安装 [Git for Windows](https://git-scm.com/download/win)，并确认 Git Credential Manager 可用。
@@ -113,7 +114,7 @@ cc-port resource registry-repair --yes --choices choices.yaml
 4. 启动 CC Port，在“设置”中粘贴仓库的 HTTPS 地址并完成验证。
 5. 扫描本机资源，在资源页逐项选择上传到仓库或安装到目标工具。
 
-安装包已经包含桌面程序和 Python sidecar；普通用户不需要安装 Python、Node.js 或 Rust。完整流程、首次配置和卸载方式见[快速开始](docs/getting-started.md)。
+本仓库的新 Windows 构建会同时包含桌面程序、Desktop API sidecar 和独立的 `cc-port.exe` CLI/MCP agent；普通用户不需要安装 Python、Node.js 或 Rust。已经发布的 v0.5.4 安装器早于这项能力，尚不包含 agent；请等待包含该功能的新版本。完整流程、首次配置、AI 集成和卸载方式见[快速开始](docs/getting-started.md)。
 
 开发环境可运行 `Set-ExecutionPolicy -Scope Process Bypass -Force; & .\scripts\setup.ps1` 自动检查并安装所需工具和依赖。脚本列出操作后会直接执行，不再要求输入 `y/n`；`-CheckOnly` 仍只检查而不修改环境。
 
@@ -122,6 +123,7 @@ cc-port resource registry-repair --yes --choices choices.yaml
 - **仓库归你所有**：CC Port 不提供托管云服务；资源保存在你指定的 Git 仓库。
 - **凭据交给系统**：桌面端通过 Git Credential Manager 使用系统凭据，不读取或保存 GitHub Token。
 - **先计划再写入**：桌面端和 CLI 在写操作前展示目标、动作与阻断原因。
+- **机器接口不提供自批准**：推荐的 MCP 与非交互 CLI 写入必须提交绑定 operation、plan hash 和完整 scope 的一次性本机审批；用户在桌面端批准，stale 后必须重新审阅。
 - **不覆盖未接管内容**：所有权标记用于区分 CC Port 管理项与手工维护项。
 - **悬空链接只替换链接本身**：下载目标是根级 Windows 原生悬空符号链接时，只有明确确认覆盖未接管目标后才会删除链接本身并写入普通内容，不会跟随或修改链接指向的位置。
 - **可恢复写入**：安装、卸载、部署和恢复使用持久化事务、备份与失败回滚。
@@ -181,12 +183,20 @@ Cursor 预设把 Prompt `<name>` 安装为全局自定义命令
 
 ## 三种入口
 
-- **桌面 GUI**：日常扫描、比较、上传、安装和环境诊断；说明页提供项目仓库与 GitHub Star 支持入口。
-- **CLI**：脚本化、批量操作、历史恢复和状态维护。
-- **MCP Server**：让支持 MCP 的 AI coding 工具调用 CC Port 能力。
+- **桌面 GUI**：日常扫描、比较、上传、安装、AI 集成、审批和环境诊断；人类界面不会删除。
+- **CLI**：人类脚本、严格 `--non-interactive --json` 机器调用、批量操作、历史恢复和状态维护。
+- **MCP Server**：`cc-port mcp --stdio` 向支持 MCP 的 AI coding 工具暴露 typed plan/apply 能力。
 
 三种入口共享同一套 Python 核心逻辑。架构边界和同步状态机见[架构文档](docs/architecture.md)。
 
+### 让 AI 自动使用 CC Port
+
+在包含该能力的新构建中，从桌面端“设置 → AI 自动化”按精确 profile 审阅启用计划。批准后，CC Port 只把随包发布的 `cc-port` Skill 安装到该 profile 的 Skill 目录，并在该工具的原生配置中增加本机 `cc-port.exe mcp --stdio` entry；不会删除客户端，也不会改写其他 MCP server。当前 schema v1 只自动引导 Windows 原生 profile；WSL profile 会显式阻断这一“Skill + MCP 注册”步骤，不会把 Windows 进程误报为 WSL 连接成功。现有的 profile-aware WSL 资源扫描和 plan/apply 能力仍保留。
+
+AI 首选 MCP discovery，并执行 `status → inventory(scan_local=true) → diff → plan → approval → apply → verify`；MCP 不可用时才回退到单 JSON envelope 的非交互 CLI。读和 plan 可自动完成，写计划进入桌面的“待处理 AI 审批”，用户单次批准后才能 apply。审批会过期且只能消费一次；目标变化返回新的 stale plan，旧审批自动失效。完整命令、schema 和安全边界见 [AI Agent 自动发现、审批与调用规格](docs/specs/ai-agent-interface.md)。
+
+这是应用层审批边界，不是 Windows 上的独立安全主体：AI 宿主必须限制 agent 直接改写 CC Port 本机 state 目录或伪造桌面 sidecar 调用。对与人类用户拥有同等、不受限制文件与进程权限的代码执行者，当前 v1 不声称提供操作系统级“人类在场”证明。
+
 ## 当前限制
 
 - Public Beta 仅正式支持 Windows 10/11 x64。
@@ -206,6 +216,7 @@ Cursor 预设把 Prompt `<name>` 安装为全局自定义命令
 - [架构](docs/architecture.md)
 - [Registry v1 规格](docs/specs/registry-v1.md)
 - [Claude Code 指令、记忆与多运行环境规格](docs/specs/claude-memory-and-runtime-environments.md)
+- [AI Agent 自动发现、审批与调用规格](docs/specs/ai-agent-interface.md)
 - [桌面打包与发布](docs/packaging-and-deployment.md)
 - [v0.5.4 发布说明](docs/releases/v0.5.4.md)
 - [功能规格](docs/specs/)