bugfix

Author: Ling-ye

README.en.md

@@ -198,19 +198,33 @@ All three interfaces share the same Python core. See the [architecture (Chinese)
 
 ### 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.
+AI automation lets Codex, Claude Code, Cursor, and other AI coding tools call the local CC Port service to scan resources, compare local and remote state, upload local resources, or install remote resources into an exact tool profile. It is not unattended background sync: the AI can inspect and prepare a plan automatically, while every write still requires your approval in the CC Port desktop app.
 
-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.
+CC Port does not call a language model, so you do not provide a separate OpenAI, Anthropic, or other model API key. The AI coding tool must already be signed in. Git Credential Manager handles private GitHub repository login, and real secrets used by third-party MCP servers remain machine-local.
 
-Read-only inventory and synchronization advice is provided by the external
+The shortest workflow is:
+
+1. Open **Settings → AI automation**, select **Review enable plan** for the Windows profile that should use CC Port, then approve and enable it.
+2. In the AI chat, enter: `Use CC Port to scan every configured profile and compare local and remote state. Read only; do not modify anything.`
+3. After choosing a direction, enter: `Upload skill:example from codex-windows to the repository. Handle only this item and show the plan first.`
+4. Review and approve it under **Settings → AI automation → Pending AI approvals**, then return to the chat and say: `I approved the plan in the CC Port desktop app. Continue and run a fresh inventory to verify the result.`
+
+If you do not know the profile id or resource key, ask the AI to list them from a fresh inventory. Prefer an explicit direction such as "upload to the repository" or "install into this profile" instead of the ambiguous word "sync." Every approval is bound to the current operation, `plan_hash`, and complete scope, expires automatically, and can be consumed once. State changes require review of a new plan.
+
+During enablement, CC Port installs only its packaged `cc-port` Skill into the selected profile and registers local `cc-port.exe mcp --stdio` in that tool's native configuration. It does not remove the desktop client or rewrite unrelated MCP servers. Schema v1 automatically bootstraps native Windows profiles only; existing WSL inventory and plan/apply workflows remain available. See [Getting started: let an AI manage resources with CC Port](docs/getting-started.en.md#5-let-an-ai-manage-resources-with-cc-port) for the complete beginner workflow and copyable prompts, or the [AI agent discovery, approval, and invocation specification (Chinese)](docs/specs/ai-agent-interface.md) for commands, schemas, and security boundaries.
+
+#### Optional: read-only Advisor
+
+Most users do not need the Advisor. Install the external
 [`cc-port-advisor`](https://github.com/Ling-ye/LingyeAIResources/tree/main/skills/cc-port-advisor)
-Skill. It reads MCP `asset_reconcile_context` (or the strict JSON CLI fallback), covers only
-configured CC Port profiles and saved projects, and never creates a plan, approval, or transfer;
-execution returns to the operational `cc-port` Skill. See the
+Skill only when you want an AI to summarize all differences and recommend next steps without ever
+creating a write plan. It covers only configured CC Port profiles and saved projects and never
+creates a plan, approval, or transfer. When you choose an action, the packaged `cc-port` Skill runs
+a fresh inventory, creates the plan, and waits for desktop approval. See the
 [AI agent interface specification (Chinese)](docs/specs/ai-agent-interface.md) for the complete
 contract and security boundaries.
 
-This is an application-level approval boundary, not a separate Windows security
+Desktop approval is an application-level safety 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

README.md

@@ -193,17 +193,31 @@ Cursor 预设把 Prompt `<name>` 安装为全局自定义命令
 
 ### 让 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 自动化让 Codex、Claude Code、Cursor 等 AI 工具调用本机 CC Port，帮你扫描资源、比较本地与远端、上传本地资源或把远端资源安装到指定工具。它不是无人值守的后台同步：AI 可以自动读取和生成计划，真正写入前仍由你在 CC Port 桌面端批准。
 
-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)。
+CC Port 不调用大模型，不需要你另外填写 OpenAI、Anthropic 或其他模型 API Key。AI 工具本身需要已经正常登录；私有 GitHub 仓库由 Git Credential Manager 完成登录，第三方 MCP 的真实密钥继续留在本机。
 
-只读盘点和同步建议由外部
+最短使用方式：
+
+1. 打开“设置 → AI 自动化”，为需要使用 CC Port 的 Windows profile 点击“审阅启用计划”，然后“批准并启用”。
+2. 在 AI 对话中输入：`使用 CC Port 扫描所有已配置 profile，只读比较本地和远端，不要修改。`
+3. 决定方向后再输入：`把 codex-windows 中的 skill:example 上传到仓库，只处理这一项，先展示计划。`
+4. 在“设置 → AI 自动化 → 待处理 AI 审批”中核对并批准，再回到对话说：`我已在 CC Port 桌面端批准，请继续执行并重新扫描验证。`
+
+如果不知道 profile id 或资源 key，先让 AI 从最新扫描结果中列出来。尽量使用“上传到仓库”或“安装到某个 profile”明确方向，不要只说含义不确定的“同步”。每次审批只绑定当前 operation、`plan_hash` 和完整范围，会自动过期且只能使用一次；状态变化后必须审阅新计划。
+
+启用时，CC Port 只把内置 `cc-port` Skill 安装到选定 profile，并在该工具的原生配置中注册本机 `cc-port.exe mcp --stdio`；不会删除桌面客户端或改写其他 MCP Server。当前 schema v1 只自动引导 Windows 原生 profile，WSL profile 仍可参与已有的资源扫描和 plan/apply。完整的新手步骤和可复制话术见[快速开始：让 AI 帮你管理资源](docs/getting-started.md#5-让-ai-帮你管理资源ai-自动化)，底层命令、schema 和安全边界见 [AI Agent 自动发现、审批与调用规格](docs/specs/ai-agent-interface.md)。
+
+#### 可选：只读 Advisor
+
+普通用户不需要安装 Advisor。只有希望“先让 AI 汇总全部差异并给出建议、但绝不创建写入计划”的用户，
+才需要外部
 [`cc-port-advisor`](https://github.com/Ling-ye/LingyeAIResources/tree/main/skills/cc-port-advisor)
-Skill 提供。它读取 MCP `asset_reconcile_context`（或严格 JSON CLI fallback），只检查 CC Port 已配置的
-profile 与保存项目，不创建计划、审批或传输；执行仍交回操作型 `cc-port` Skill。完整接口和安全边界见
+Skill。它只检查 CC Port 已配置的 profile 与保存项目，不创建计划、审批或传输。用户决定执行后，
+仍由上面的内置 `cc-port` Skill 重新扫描、生成计划并等待桌面审批。完整接口和安全边界见
 [AI Agent 自动发现、审批与调用规格](docs/specs/ai-agent-interface.md)。
 
-这是应用层审批边界，不是 Windows 上的独立安全主体：AI 宿主必须限制 agent 直接改写 CC Port 本机 state 目录或伪造桌面 sidecar 调用。对与人类用户拥有同等、不受限制文件与进程权限的代码执行者，当前 v1 不声称提供操作系统级“人类在场”证明。
+桌面审批是应用层安全护栏，不是 Windows 上的独立安全主体：AI 宿主仍需限制 agent 直接改写 CC Port 本机 state 目录或伪造桌面 sidecar 调用。对与人类用户拥有同等、不受限制文件与进程权限的代码执行者，当前 v1 不声称提供操作系统级“人类在场”证明。
 
 ## 当前限制
 

desktop/src/app/i18n/catalog.ts

@@ -145,6 +145,7 @@ export const en = {
   "message.asset.blocker.read_only_download": "Read-only references cannot be downloaded from the private asset snapshot.",
   "message.asset.blocker.read_only_reference": "This registry item is a read-only reference in asset sync.",
   "message.asset.blocker.registry_unavailable": "The remote registry is unavailable; remote resource actions are blocked.",
+  "message.asset.blocker.registry_upgrade_required": "The remote repository still uses Registry v7. Upgrade it to Registry v1 to restore remote asset operations.",
   "message.asset.blocker.remote_asset_missing": "The remote asset does not exist.",
   "message.asset.blocker.remote_name_exists": "The new name already exists in the remote registry for this kind.",
   "message.asset.blocker.remote_read_only": "The matching remote item is read-only; save it under a new remote name.",
@@ -188,6 +189,8 @@ export const en = {
   "message.asset.platform_diff.target_conflict": "Multiple resources resolve to the same platform target.",
   "message.asset.platform_diff.uncomparable": "The content cannot be compared safely.",
   "message.asset.remote.not_configured": "No remote resource repository is configured; remote writes are blocked.",
+  "message.asset.remote.registry_unavailable": "The remote Registry is unavailable. Remote asset operations remain blocked.",
+  "message.asset.remote.registry_upgrade_required": "The remote repository uses Registry v7. Upgrade it to Registry v1 before using remote assets.",
   "message.asset.remote.refresh_failed_cached": "Remote refresh failed. Showing the cached snapshot from {cached_at}: {detail}",
   "message.asset.remote.refresh_failed_legacy": "Remote refresh failed. Showing the legacy local snapshot read-only: {detail}",
   "message.asset.remote.refresh_skipped_cached": "Remote refresh was skipped. Showing the cached snapshot from {cached_at}.",
@@ -387,9 +390,14 @@ export const en = {
   "registry.status.legacy": "Legacy registry",
   "registry.status.missing": "Registry missing",
   "registry.status.unavailable": "Registry unavailable",
+  "registry.status.upgradeRequired": "Registry upgrade required",
   "registry.suggestedAction": "Action",
   "registry.unchanged": "registry.yaml is already unchanged.",
   "registry.updatePreview": "Update preview",
+  "registry.upgradeAction": "Upgrade to Registry v1",
+  "registry.upgradeDescription": "This repository still uses Registry v7, which CC Port keeps read-only. Review the migration to rebuild registry.yaml from current repository content and restore asset details, uploads, and installs.",
+  "registry.upgradeRequiredShort": "Upgrade the remote repository to Registry v1 before collecting or importing assets.",
+  "registry.upgradeTitle": "Remote Registry needs an upgrade",
   "message.registry.issue.duplicate_key": "Multiple entries use the same resource identity {resource_key}. Select the entry to keep.",
   "message.registry.issue.duplicate_path": "Multiple entries use the same repository path {path}. Select the entry to keep.",
   "message.registry.issue.invalid_resource": "The resource at {path} does not satisfy its content format.",
@@ -1097,9 +1105,14 @@ export const zh: Record<I18nKey, string> = {
   "registry.status.legacy": "旧版 Registry",
   "registry.status.missing": "Registry 缺失",
   "registry.status.unavailable": "Registry 不可用",
+  "registry.status.upgradeRequired": "Registry 需要升级",
   "registry.suggestedAction": "处理动作",
   "registry.unchanged": "registry.yaml 已经无需修改。",
   "registry.updatePreview": "更新预览",
+  "registry.upgradeAction": "升级到 Registry v1",
+  "registry.upgradeDescription": "该仓库仍使用 Registry v7，CC Port 会保持只读。请审阅迁移计划：它将依据当前仓库内容重建 registry.yaml；完成后即可恢复资产详情、上传和安装。",
+  "registry.upgradeRequiredShort": "请先将远端仓库升级到 Registry v1，再收集或导入资产。",
+  "registry.upgradeTitle": "远端 Registry 需要升级",
   "message.registry.issue.duplicate_key": "多个条目使用相同资源身份 {resource_key}，请选择要保留的条目。",
   "message.registry.issue.duplicate_path": "多个条目使用相同仓库路径 {path}，请选择要保留的条目。",
   "message.registry.issue.invalid_resource": "路径 {path} 中的资源不符合对应内容格式。",
@@ -1245,6 +1258,7 @@ export const zh: Record<I18nKey, string> = {
   "message.asset.blocker.read_only_download": "不能从私有资产快照下载只读引用。",
   "message.asset.blocker.read_only_reference": "该注册表项目在资产同步中是只读引用。",
   "message.asset.blocker.registry_unavailable": "远端 Registry 不可用，所有远端资源操作均已阻断。",
+  "message.asset.blocker.registry_upgrade_required": "远端仓库仍使用 Registry v7；升级到 Registry v1 后即可恢复远端资产操作。",
   "message.asset.blocker.remote_asset_missing": "远端资产不存在。",
   "message.asset.blocker.remote_name_exists": "远端注册表中已存在该类型和名称。",
   "message.asset.blocker.remote_read_only": "匹配的远端项目为只读，请使用新名称保存远端副本。",
@@ -1288,6 +1302,8 @@ export const zh: Record<I18nKey, string> = {
   "message.asset.platform_diff.target_conflict": "多个资源解析到了同一平台目标。",
   "message.asset.platform_diff.uncomparable": "无法安全比较内容。",
   "message.asset.remote.not_configured": "未配置远端资源仓库，已阻止远端写入。",
+  "message.asset.remote.registry_unavailable": "远端 Registry 不可用，远端资产操作仍处于阻断状态。",
+  "message.asset.remote.registry_upgrade_required": "远端仓库使用 Registry v7，请先升级到 Registry v1 再使用远端资产。",
   "message.asset.remote.refresh_failed_cached": "远端刷新失败，正在显示 {cached_at} 的缓存快照：{detail}",
   "message.asset.remote.refresh_failed_legacy": "远端刷新失败，正在只读显示旧本地快照：{detail}",
   "message.asset.remote.refresh_skipped_cached": "已跳过远端刷新，正在显示 {cached_at} 的缓存快照。",