code-workspace-zhuiyi 0.1.0-beta.1

package/docs/extension-architecture.zh-CN.md

@@ -0,0 +1,429 @@
+# Code Workspace 扩展架构
+
+> 本文是面向维护者的说明性架构文档。Extension Spec 的规范性定义以 `spec/extension/v1/specification.zh-CN.md` 及其引用的 JSON Schema 为准；本文不单独建立兼容性或一致性规则。
+
+本文定义 Code Workspace 扩展的基础架构、核心术语、职责边界和最小生命周期协议。它是后续扩展实现与评审的共同基线。
+
+本文追求的是一版基础、稳健、务实且完整闭环的架构。它只覆盖当前已经出现并能够验证的需求，不试图一次解决未知的扩展市场、安全沙箱、任意外部副作用或所有配置格式。
+
+## 1. 架构目标
+
+扩展架构需要同时满足以下目标：
+
+- 新增一个使用既有协议能力的扩展时，不修改扩展核心代码和公共 schema。
+- 扩展自行掌握下载、解压、构建、包校验和内容生成等业务知识。
+- Host 统一管理发现、确认、锁、事务、冲突、状态、回滚、升级和卸载。
+- 扩展失败不能向真实 Workspace 留下未经 Host 提交的半成品。
+- Host 能够仅依赖已安装状态完成验证和卸载，不需要再次执行扩展代码。
+- 共享文件中的扩展贡献可以独立安装、升级和移除，不破坏用户、核心或其他扩展的内容。
+- 协议可以通过版本演进补充新的通用能力，但不预先猜测未来扩展类型。
+
+架构的核心边界是：
+
+> 扩展负责如何准备内容；Host 负责是否允许、提交到哪里、如何提交以及如何撤销。
+
+Host 不理解 Jira、npm、tar.gz 或某个具体 Agent 的业务含义，但必须理解并治理扩展产生的可观察副作用。
+
+## 2. 非目标
+
+基础版明确不解决以下问题：
+
+- 不执行来自任意第三方的不可信扩展。
+- 不提供安全沙箱、容器或操作系统级文件和网络隔离。
+- 不提供扩展市场、动态安装扩展包或远程扩展发现。
+- 不提供任意 Workspace 外部副作用及其补偿机制。
+- 不允许扩展自定义卸载脚本。
+- 不负责管理扩展运行后产生的业务数据，例如 Jira 附件。
+- 不提供通用包管理器、通用归档格式或通用构建系统。
+- 不建立扩展之间的依赖、服务发现或调用协议。
+- 不建立可以合并任意文本、JSON、TOML、YAML 或数据库内容的万能 contribution 引擎。
+- 不提供强制覆盖或强制卸载未知本地修改的模式。
+
+出现这些真实需求时，应作为独立能力评估，而不是提前加入基础协议。
+
+## 3. 信任模型
+
+基础版扩展是随 Code Workspace 发布或由 Code Workspace 明确批准的可信代码。
+
+这里的“可信”表示 Host 允许该代码以当前用户身份执行，不表示扩展运行在安全沙箱中。普通 Node.js 子进程即使使用受限环境变量、固定工作目录和 staging 参数，仍然不是安全边界。
+
+因此需要区分两类约束：
+
+- 协议约束：扩展必须只在 Host 提供的 staging 中准备候选制品，不得直接修改真实 Workspace。
+- Host 保证：Host 不会提交未声明、越界、冲突或校验失败的 staging 内容。
+
+Host 可以通过不提供真实 Workspace 路径、限制上下文和环境变量来降低误操作风险，但不能据此宣称能够防御恶意扩展。
+
+## 4. 核心术语
+
+### 4.1 Host
+
+Host 是 Code Workspace 中负责扩展生命周期治理的核心实现。Host 发现扩展、验证协议、执行入口、检查候选制品，并将合法结果提交到 Workspace。
+
+### 4.2 扩展仓库
+
+扩展仓库是 Code Workspace 发布包中用于保存内置扩展的目录集合。基础版不从网络发现或安装扩展定义。
+
+### 4.3 扩展包
+
+扩展包是一个符合扩展协议的、具有明确 id 和版本的可执行目录：
+
+```text
+extensions/<extension-id>/<version>/
+├── manifest.json
+├── init.js
+└── <扩展私有的模板、元数据和辅助代码>
+```
+
+扩展包包含“如何初始化”的代码和资源，但它本身不是安装到 Workspace 的制品。
+
+### 4.4 静态 manifest
+
+`manifest.json` 是扩展执行前可读取和验证的静态合同。扩展与 Host 的兼容性由 Extension Spec 版本决定，而不是由任一方的产品版本决定。它声明：
+
+- 扩展实现的 Extension Spec 版本、身份和扩展版本；
+- 初始化入口、入口摘要和执行超时；
+- 扩展有意使用的能力，例如网络目标；
+- 可能产生的输出及其最大目标范围；
+- 不同工具选择下哪些输出适用。
+
+Host 明确声明自己支持的 Extension Spec 版本集合，只有 manifest 的 `extensionSpecVersion` 属于该集合时才会执行扩展。静态 manifest 用于发现、规划、冲突预检和用户确认。它不描述扩展业务实现，不包含需要由 Host 理解的下载 URL、npm 包信息或归档格式。
+
+入口可能继续读取扩展包内的辅助代码、模板和私有元数据，因此仅校验 `init.js` 不能冻结完整执行输入。Host 在规划时还需要计算整个扩展版本目录的规范摘要，并在执行前重新验证，以防 manifest、入口、辅助代码或模板在计划确认后发生变化。
+
+### 4.5 初始化入口
+
+初始化入口是扩展包提供的可执行程序。基础版使用 Node.js `init.js`，由 Host 以固定协议启动。
+
+初始化入口负责准备候选制品并生成初始化结果，不负责持有 Workspace 锁、提交真实文件或写入已安装状态。
+
+### 4.6 staging
+
+staging 是 Host 为单次扩展执行创建的临时输出目录。扩展的所有候选制品必须先生成在 staging 中。
+
+staging 内容在验证和提交前不属于 Workspace，也不代表扩展已经安装。
+
+### 4.7 候选制品
+
+候选制品是扩展在 staging 中生成、等待 Host 验证和提交的文件、目录或共享内容片段。
+
+候选制品只有在 Host 完成校验、提交和后置验证后，才成为已安装制品。
+
+### 4.8 contribution
+
+contribution 是安装到共享目标中的、由单个扩展拥有的局部内容。共享目标可能同时包含用户、核心和其他扩展的内容，因此不能按普通独占文件整体覆盖或删除。
+
+基础版只引入当前确实需要、具有确定合并和移除语义的 contribution 处理能力。
+
+### 4.9 初始化结果
+
+初始化结果是扩展执行完成后写出的机器可读结果。它只报告本次实际生成了哪些静态声明输出，以及这些输出在 staging 中的来源。
+
+初始化结果是扩展的声明，不是最终安装事实。Host 必须独立验证内容并计算摘要。
+
+### 4.10 installed manifest
+
+installed manifest 是 Host 持久化的最终安装事实，保存在 Workspace 的扩展状态中。它记录实际版本、所有权、目标、Host 计算的摘要和卸载所需的共享 contribution 信息。
+
+安装、幂等判断、升级、漂移检查和卸载均以 installed manifest 为依据。静态 manifest 和初始化结果不能替代它。
+
+### 4.11 用户数据
+
+用户数据是扩展安装完成并运行后，由用户或扩展业务进程产生的内容，例如 `.jira-attachments/`。
+
+除非未来引入独立且明确的用户数据协议，否则用户数据不属于安装制品，不写入初始化结果，也不由扩展卸载流程删除。
+
+## 5. 扩展与 Host 的职责边界
+
+| 事项 | 扩展负责 | Host 负责 |
+|---|---|---|
+| 业务知识 | 下载地址、归档格式、包结构、构建方式、配置内容 | 不理解具体业务 |
+| 执行 | 在 staging 中准备候选制品 | 创建执行环境、传入上下文、控制超时、收集结果 |
+| 能力 | 静态声明有意使用的能力 | 校验、展示、确认和记录能力；基础版不宣称具备 OS 级强制隔离 |
+| 输出目标 | 在静态 manifest 中声明允许目标 | 规范化路径、禁止越界、保护核心目标、检查所有权冲突 |
+| 完整性 | 可执行扩展私有的业务校验 | 独立枚举输出、拒绝额外内容、计算已安装摘要 |
+| Workspace 写入 | 不直接写入 | 独占提交、共享内容合成、状态写入和后置验证 |
+| 事务 | 不实现 | 锁、备份、提交、补偿回滚和清理 |
+| 升级 | 生成新版本候选制品 | 比较旧状态、检查漂移、替换和移除过期制品 |
+| 卸载 | 不提供卸载脚本 | 仅依据 installed manifest 验证和移除 Host 已拥有内容 |
+| 用户数据 | 业务进程可以在运行期产生 | 默认不拥有、不删除 |
+
+以下职责不得下沉到扩展：
+
+- 获取或释放 Workspace 操作锁；
+- 直接修改 `.code-workspace/ext-manifest.json`；
+- 决定冲突时覆盖其他扩展或用户内容；
+- 绕过 Host 直接提交真实 Workspace；
+- 在卸载时执行任意脚本；
+- 将 Cookie、Token 等秘密写入结果、状态或日志。
+
+## 6. 基础版输出模型
+
+基础版只支持已经有明确需求和可验证生命周期语义的输出。
+
+### 6.1 独占文件
+
+一个扩展独占一个 Workspace 相对文件目标。Host 负责：
+
+- 拒绝核心保护目标和已被其他扩展拥有的目标；
+- 安装时写入或替换同一扩展的旧版本；
+- 记录文件摘要；
+- 卸载前验证文件未发生未知修改；
+- 验证成功后删除该文件。
+
+### 6.2 独占目录
+
+一个扩展独占一个 Workspace 相对目录目标。它用于安装包含多个文件的运行时，例如预构建的 Jira MCP 包。
+
+Host 将目录视为一个制品，使用规范化目录摘要检测漂移，并通过 staging、备份和 rename 完成可恢复提交。目录摘要算法必须固定路径规则、排序、文件类型和文件内容计算方式。
+
+### 6.3 共享文本块
+
+扩展提供一个文本片段，Host 使用稳定的扩展 id 和输出 id 标记，将其合成到声明的共享文本目标中。
+
+Host 负责：
+
+- 标记的生成、唯一性和顺序；
+- 最终文档的必要格式验证；
+- 安装、升级和卸载时保留标记之外的内容；
+- 检测标记丢失、重复或块内容被修改。
+
+该能力覆盖当前 Codex TOML 配置需求，但协议不包含 Codex 或 MCP 业务字段。
+
+### 6.4 JSON 对象成员
+
+扩展提供一个 JSON 值，并在静态 manifest 中声明目标文件和唯一成员位置。Host 只拥有该成员，不拥有整个 JSON 文件。
+
+Host 负责：
+
+- 验证目标文档和 selector；
+- 拒绝同一位置的未知内容或其他扩展所有权；
+- 保留其他顶层字段和成员；
+- 记录规范化后的已安装值；
+- 卸载时仅移除仍与安装记录一致的成员。
+
+该能力覆盖 `.mcp.json` 中单个 MCP server 的需求，但核心不验证 server 的 Jira 业务含义。
+
+### 6.5 暂不增加的输出
+
+基础版不增加 `remote-archive` 之类的下载型制品。下载和解压是扩展准备候选目录的实现过程，不是 Host 的安装制品语义。
+
+基础版也不增加通用 `external-effect` 或 `user-data` 制品。二者尚不具备可验证、可回滚和可卸载的统一语义。
+
+现有其他共享能力在迁移期间可以保留兼容处理，但不能据此继续增加与具体工具或扩展同名的公共 artifact 类型。
+
+## 7. 静态 manifest 与动态结果
+
+静态 manifest 声明最大权限范围。Host 先根据工具选择得到本次适用输出，初始化结果必须完整返回这组适用输出，既不能扩大范围，也不能静默缺失。工具选择使本次输出成为完整静态声明的确定子集。
+
+下面是逻辑示例，具体字段名由对应 JSON Schema 固化：
+
+```json
+{
+  "schemaVersion": 3,
+  "extensionSpecVersion": 1,
+  "id": "zhuiyi-jira-mcp",
+  "version": "0.1.0",
+  "entry": "init.js",
+  "entrySha256": "<sha256>",
+  "timeoutMs": 120000,
+  "capabilities": {
+    "networkHosts": ["gitee.com", "raw.giteeusercontent.com"]
+  },
+  "outputs": [
+    {
+      "id": "runtime",
+      "kind": "directory",
+      "ownership": "exclusive",
+      "target": ".code-workspace/extensions/zhuiyi-jira-mcp/0.1.0"
+    },
+    {
+      "id": "codex-config",
+      "kind": "text-block",
+      "ownership": "shared",
+      "target": ".codex/config.toml",
+      "tools": ["codex"]
+    },
+    {
+      "id": "claude-config",
+      "kind": "json-member",
+      "ownership": "shared",
+      "target": ".mcp.json",
+      "selector": "/mcpServers/zhuiyi-jira",
+      "tools": ["claude"]
+    }
+  ]
+}
+```
+
+下载 URL、远程包 SHA-256、归档根目录和包内入口等内容属于 Jira 扩展的私有实现，可以保存在扩展代码或扩展私有元数据中。Host 不解析这些字段。
+
+Host 使用独立的临时路径启动扩展：
+
+```text
+node init.js --context <context-file> --output <staging-directory> --result <result-file>
+```
+
+初始化结果只引用静态输出 id 和 staging 来源，不重新声明真实目标、所有权或摘要：
+
+```json
+{
+  "schemaVersion": 1,
+  "extension": {
+    "id": "zhuiyi-jira-mcp",
+    "version": "0.1.0"
+  },
+  "outputs": [
+    { "id": "runtime", "source": "runtime" },
+    { "id": "codex-config", "source": "codex-config.toml" },
+    { "id": "claude-config", "source": "claude-server.json" }
+  ]
+}
+```
+
+这种设计避免扩展执行完成后再扩大目标范围。摘要由 Host 从 staging 实际内容计算，不信任扩展自报摘要。
+
+## 8. 完整生命周期
+
+### 8.1 安装
+
+```text
+发现扩展并验证静态 manifest
+→ 从 Host 支持的 Extension Spec 实现中解析最高扩展版本和适用输出
+→ 检查声明能力、目标范围和已知冲突
+→ 展示计划并确认
+→ 获取 Workspace 操作锁并重新验证计划
+→ 创建 context、staging 和 result 临时路径
+→ 执行 init.js
+→ 验证初始化结果完整匹配本次适用的静态输出
+→ 枚举 staging，拒绝未声明文件、特殊文件、符号链接和路径逃逸
+→ Host 计算文件或目录摘要并验证 contribution
+→ 检查当前 Workspace 所有权和本地漂移
+→ 在单扩展可恢复事务中提交独占制品、共享 contribution 和 installed manifest
+→ 验证完整后置条件
+→ 提交事务、清理 staging、释放锁
+```
+
+扩展在提交前失败时，Host 只清理临时目录，真实 Workspace 保持不变。提交阶段失败时，Host 使用备份和补偿操作恢复原状态。
+
+这里的事务是文件系统上的可恢复事务，不承诺数据库级的跨文件原子性。
+
+### 8.2 幂等安装
+
+只有同时满足以下条件时，Host 才能判定扩展已经是目标状态：
+
+- 已安装扩展 id、版本和静态 manifest 身份一致；
+- 已安装输出集合与本次计划一致；
+- 所有独占文件和目录摘要一致；
+- 所有共享 contribution 仍存在且与 installed manifest 一致。
+
+仅有成功状态记录，不能证明当前 Workspace 仍然正确。
+
+### 8.3 升级
+
+升级由 Host 视为同一扩展旧状态到新状态的一次事务转换：
+
+- 输出 id 是稳定的逻辑所有权键；
+- 新旧同一输出可以替换内容或目标；
+- 新版本不再声明的旧输出需要在验证未漂移后移除；
+- 新增输出按正常冲突规则安装；
+- 任一步骤失败时恢复旧版本制品和旧 installed manifest。
+
+扩展不负责读取或修改旧 installed manifest，也不执行卸载脚本。
+
+### 8.4 卸载
+
+卸载只读取 installed manifest，不读取当前扩展包，也不执行 `init.js`：
+
+```text
+读取并验证 installed manifest
+→ 获取 Workspace 操作锁
+→ 验证独占制品和共享 contribution 未发生未知修改
+→ 创建备份并移除扩展拥有的独占制品
+→ 从共享目标中移除该扩展 contribution
+→ 更新 installed manifest
+→ 验证其他内容和用户数据仍然存在
+→ 提交事务并释放锁
+```
+
+如果已安装内容发生未知修改，基础版拒绝卸载并给出稳定诊断，不进行猜测性删除。
+
+### 8.5 初始化异常与进程中断
+
+- `init.js` 超时、异常退出或未生成结果：安装失败，清理 staging。
+- 结果无法解析或扩展身份不一致：安装失败，不提交。
+- 输出缺失、额外、越界或包含不支持的文件类型：安装失败，不提交。
+- Host 进程在提交阶段失败：通过事务备份恢复；若无法完全恢复，必须报告明确的残留状态，不能写入成功记录。
+
+## 9. 所有权与状态原则
+
+扩展输出的稳定所有权键是：
+
+```text
+<extension-id>/<output-id>
+```
+
+所有权遵循以下规则：
+
+- 独占目标同时只能由一个扩展拥有。
+- 共享目标由 Host 管理多个局部 contribution 的所有权。
+- 静态 manifest 是安装意图，不是已安装事实。
+- 初始化结果是扩展声明，不是可信事实。
+- installed manifest 是 Host 验证后的事实来源。
+- Host 只删除自己记录且仍能验证的内容。
+- 用户数据和未知内容默认保留。
+
+installed manifest 至少需要记录：
+
+- 扩展 id、版本、静态 manifest 身份和执行时冻结的扩展包摘要；
+- 输出 id、类型、所有权和真实目标；
+- Host 计算的文件或目录摘要；
+- 共享 contribution 的 selector、规范化内容或可验证摘要；
+- 支持幂等、升级和卸载所需的协议版本。
+
+installed manifest、日志和诊断不得记录 Cookie、Token 或其他真实凭证。
+
+## 10. 协议演进原则
+
+“新增扩展不修改核心和 schema”只适用于新扩展完全使用现有协议能力的情况。
+
+当出现新的可观察副作用，且 Host 无法使用现有语义安全提交、验证或卸载时，才允许扩展公共协议。例如未来确实需要管理 Workspace 外部资源，就必须先定义其确认、幂等、补偿和卸载语义，再增加新的 Host 能力。
+
+协议演进必须满足：
+
+- 新能力是跨扩展可复用的副作用语义，而不是某个产品或扩展名称；
+- Host 对该能力具有完整的安装、验证、升级和卸载闭环；
+- schema、实现、错误码、状态和测试一起版本化；
+- Host 以明确集合声明支持的 Extension Spec，扩展声明唯一规范版本；
+- 产品版本和规范版本之间不存在推测性映射；
+- 未知规范或能力安全失败，不进行数值范围猜测。
+
+## 11. 当前实现对应关系
+
+当前基础实现已经移除 Host 中曾经草拟的下载归档和 Claude MCP 专用输出分支，按以下边界实现：
+
+- Jira 扩展的 `init.js` 自行完成下载、固定 SHA-256 校验、安全解压和包结构校验。
+- Host 只接收并提交初始化后产生的独占目录。
+- Claude MCP 配置使用共享 JSON 成员能力，不在核心中保留 MCP server 专用类型。
+- Codex 配置使用共享文本块能力，不在协议中包含 Jira 字段。
+- 目录摘要、目录事务、状态回滚、共享内容重建和卸载验证等通用能力继续由 Host 管理并复用。
+- 现有 installed manifest 的读取和卸载兼容需要单独验证，不能因重构而遗失用户已经安装的内容。
+
+## 12. 基础版验收标准
+
+基础架构至少需要通过以下事实性验收：
+
+1. 新增另一个使用相同文件、目录或 contribution 能力的扩展时，不修改核心分支和公共 schema。
+2. 扩展在初始化任意阶段失败，真实 Workspace 不出现候选制品或成功状态。
+3. 扩展不能通过初始化结果扩大静态 manifest 声明的目标范围。
+4. staging 中存在未声明输出、符号链接、特殊文件或路径逃逸时，Host 拒绝安装。
+5. 已安装摘要由 Host 计算，而不是直接采用扩展报告值。
+6. 独占目标冲突和共享 selector 冲突在提交前失败。
+7. 提交或状态写入失败能够恢复安装前状态。
+8. 重复安装能验证真实 Workspace 后返回幂等结果。
+9. 升级能同时处理保留、新增、替换和移除的输出，并在失败时恢复旧状态。
+10. 卸载不执行扩展代码，并保留用户、核心、其他扩展和运行期用户数据。
+11. 本地未知修改不会被静默覆盖或删除。
+12. Jira MCP 下载、解压和包校验逻辑全部位于 Jira 扩展内部，核心代码和公共 schema 不出现 Jira、MCP、npm、tar.gz 或下载 URL 等领域字段。
+
+满足这些条件后，基础版才形成从声明、执行、验证、提交、状态到卸载的完整闭环。

package/docs/extensions.md

@@ -0,0 +1,64 @@
+# Built-in Extension Contract
+
+Code Workspace extensions are trusted, versioned packages shipped under `extensions/<id>/<semver>/`. The extension process is fault-isolated, but it is not a security sandbox: bundled extension code runs with the current user's operating-system permissions.
+
+Each version contains `manifest.json`, `init.js`, and any private templates, metadata, or helper code it needs. The current Host explicitly supports Extension Spec v1, defined in English at `spec/extension/v1/specification.en-US.md` and in Chinese at `spec/extension/v1/specification.zh-CN.md`, with these component schemas:
+
+- `schemas/extension-manifest-v3.json`
+- `schemas/extension-init-context-v1.json`
+- `schemas/extension-init-result-v1.json`
+
+The static manifest declares its `extensionSpecVersion`, identity, entry hash and timeout, declarative network hosts, and maximum output scope. The Host executes only explicitly supported specification versions; the Code Workspace product version is not an extension compatibility key. Code Workspace freezes the specification version, manifest, entry, and complete extension-version directory digest before confirmation, then verifies them again before execution.
+
+The Host starts the entry with independent temporary paths:
+
+```text
+node init.js --context <context-file> --output <staging-directory> --result <result-file>
+```
+
+The context contains the specification version, extension identity, Workspace display metadata, and selected tools. It does not expose the real Workspace path. The result echoes the same specification version and contains only the extension identity and `{ id, source }` entries. It must return exactly every manifest output applicable to the selected tools; it cannot redefine target, kind, ownership, selector, or digest.
+
+The Host recursively validates staging, rejects undeclared content, path escapes, symbolic links, and special files, and independently computes installed file and directory digests. Extensions never write the real Workspace or installed state directly and never provide uninstall code.
+
+## Generic output kinds
+
+- `file`: one extension-owned Workspace-relative regular file.
+- `directory`: one extension-owned Workspace-relative directory tree containing only regular files and directories.
+- `text-block`: a Host-marked fragment in a shared text file. `format: "toml"` validates both the fragment and the complete composed document.
+- `json-member`: one JSON value owned at a declared JSON Pointer in a shared object document.
+
+Exclusive targets cannot overlap core-managed paths or another extension's targets. Shared text blocks can coexist in the same text target. JSON member ownership rejects equal or parent/child selectors. The Host preserves user, core, and other extension content during install, upgrade, rollback, and uninstall.
+
+Download protocols, archive formats, package managers, Jira, MCP, and individual Agent products are not public output kinds. An extension may use those details privately to prepare a candidate file or directory in staging. Declarative `networkHosts` are shown in the plan for review; they are not operating-system-level egress enforcement.
+
+The installed manifest is the only installation fact. New records contain the installed-record version, Extension Spec version, extension version, frozen package and manifest digests, generic output ownership, Host-computed digests, and shared contribution data. Idempotency verifies both this state and the real Workspace. Upgrade handles retained, added, replaced, and removed outputs in one per-extension recoverable transaction. Uninstall reads only installed state, so it still works when the bundled package or execution specification is absent. Unknown local changes stop upgrade or uninstall; there is no force mode.
+
+Previously published installed protocol-v1/v2 records for files, Codex configuration blocks, and Codex Hooks remain readable and uninstallable. They are compatibility state, not new Extension Spec v1 output kinds.
+
+`init`, `extension install`, and `extension uninstall` share one non-blocking per-Workspace operation lock. A multi-extension install uses one confirmation boundary and an independent transaction per extension; a failure does not stop later extensions, but the overall command reports failure.
+
+## Zhuiyi Jira MCP
+
+Install it with:
+
+```bash
+code-w extension install zhuiyi-jira-mcp --yes
+```
+
+The Jira extension privately downloads the pinned Gitee release, verifies its fixed SHA-256, safely extracts it, and validates the npm package name, version, and `dist/index.js` entry inside staging. The archive already contains `dist` and runtime dependencies; initialization never runs `npm install`, `npm ci`, a build, or an archive script.
+
+After validation, the Host installs only generic outputs:
+
+```text
+.code-workspace/extensions/zhuiyi-jira-mcp/0.1.0/   # directory
+.codex/config.toml                                  # text-block when Codex is selected
+.mcp.json#/mcpServers/zhuiyi-jira                   # json-member when Claude is selected
+```
+
+The generated configuration contains non-secret defaults only. It never persists a Jira cookie, token, email, or password; provide credentials in the environment that launches the Agent, for example:
+
+```bash
+export JIRA_COOKIE='JSESSIONID=...; atlassian.xsrf.token=...'
+```
+
+Downloaded attachments default to `.jira-attachments/` in the Workspace. They are runtime user data, not installation artifacts, and are retained when the extension is upgraded or uninstalled.

package/docs/extensions.zh-CN.md

@@ -0,0 +1,64 @@
+# 内置扩展契约
+
+Code Workspace 扩展是随发布包提供、位于 `extensions/<id>/<semver>/` 下的可信版本化软件包。扩展进程具有故障隔离，但不是安全沙箱：内置扩展代码仍以当前用户的操作系统权限运行。
+
+每个版本包含 `manifest.json`、`init.js`，以及扩展需要的私有模板、元数据或辅助代码。当前 Host 明确支持 Extension Spec v1；中文规范位于 `spec/extension/v1/specification.zh-CN.md`，英文规范位于 `spec/extension/v1/specification.en-US.md`，其组件 schema 为：
+
+- `schemas/extension-manifest-v3.json`
+- `schemas/extension-init-context-v1.json`
+- `schemas/extension-init-result-v1.json`
+
+静态 manifest 通过 `extensionSpecVersion` 声明扩展实现的开发规范，并声明扩展身份、入口摘要和超时、声明性网络 host，以及最大输出范围。Host 只执行其明确支持的规范版本；Code Workspace 产品版本不参与扩展兼容判断。Code Workspace 在确认前冻结规范版本、manifest、入口和完整扩展版本目录摘要，并在执行前重新验证。
+
+Host 使用相互独立的临时路径启动入口：
+
+```text
+node init.js --context <context-file> --output <staging-directory> --result <result-file>
+```
+
+context 只包含规范版本、扩展身份、Workspace 显示元数据和所选工具，不提供真实 Workspace 路径。result 回显同一规范版本，并只包含扩展身份和 `{ id, source }`。它必须完整返回本次工具选择所适用的全部 manifest 输出，不能重新声明 target、kind、ownership、selector 或摘要。
+
+Host 递归验证 staging，拒绝未声明内容、路径逃逸、符号链接和特殊文件，并独立计算已安装文件或目录摘要。扩展不直接写入真实 Workspace 或 installed 状态，也不提供卸载脚本。
+
+## 通用输出类型
+
+- `file`：扩展独占的一个 Workspace 相对普通文件。
+- `directory`：扩展独占的一个 Workspace 相对目录树，其中只能包含普通文件和目录。
+- `text-block`：Host 使用稳定标记管理的共享文本片段；`format: "toml"` 会同时验证片段和合成后的完整文档。
+- `json-member`：扩展在共享 JSON 对象文档的声明 JSON Pointer 位置拥有一个值。
+
+独占目标不能与核心管理路径或其他扩展目标重叠。多个共享文本块可以共存于同一文本文件；JSON 成员所有权会拒绝相同 selector 及父子 selector。安装、升级、回滚和卸载均保留用户、核心及其他扩展的内容。
+
+下载协议、归档格式、包管理器、Jira、MCP 和具体 Agent 产品都不是公共输出类型。扩展可以在私有实现中使用这些知识，在 staging 中准备候选文件或目录。声明的 `networkHosts` 会展示在计划中供用户确认，但不代表操作系统级网络出口强制隔离。
+
+installed manifest 是唯一安装事实。新记录包含 installed record 版本、Extension Spec 版本、扩展版本、冻结的扩展包和 manifest 摘要、通用输出所有权、Host 计算的摘要及共享 contribution 数据。幂等判断同时验证状态和真实 Workspace。升级在单扩展可恢复事务中处理保留、新增、替换和移除的输出。卸载只读取 installed 状态，因此扩展包或执行规范已经不存在时仍可工作。发现未知本地修改时，升级或卸载会停止；基础版不提供强制模式。
+
+已经发布的 installed protocol v1/v2 文件、Codex 配置块和 Codex Hooks 记录仍可读取和卸载；它们只属于兼容状态，不再是 Extension Spec v1 的新输出类型。
+
+`init`、`extension install` 和 `extension uninstall` 共用同一个非阻塞 Workspace 操作锁。多扩展安装只确认一次，每个扩展使用独立事务；单个失败不会阻止后续扩展，但整体命令会报告失败。
+
+## Zhuiyi Jira MCP
+
+安装：
+
+```bash
+code-w extension install zhuiyi-jira-mcp --yes
+```
+
+Jira 扩展在私有实现中下载固定的 Gitee 发布包，校验固定 SHA-256，安全解压，并在 staging 中验证 npm 包名称、版本和 `dist/index.js` 入口。归档已经包含 `dist` 和运行依赖；初始化不会执行 `npm install`、`npm ci`、构建或归档内脚本。
+
+验证完成后，Host 只安装通用输出：
+
+```text
+.code-workspace/extensions/zhuiyi-jira-mcp/0.1.0/   # directory
+.codex/config.toml                                  # 选择 Codex 时的 text-block
+.mcp.json#/mcpServers/zhuiyi-jira                   # 选择 Claude 时的 json-member
+```
+
+生成配置只包含非敏感默认值，不会持久化 Jira Cookie、Token、邮箱或密码。用户需要在启动 Agent 的环境中提供凭证，例如：
+
+```bash
+export JIRA_COOKIE='JSESSIONID=...; atlassian.xsrf.token=...'
+```
+
+下载附件默认保存在 Workspace 的 `.jira-attachments/`。它是运行期用户数据，不是安装制品，扩展升级或卸载时都会保留。

package/extensions/openspec-workspace/1.0.0/artifacts/claude/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: code-workspace-openspec-propose
+description: Create an OpenSpec change for a selected Code Workspace project after resolving and verifying that project's registered scope.
+---
+
+# Code Workspace OpenSpec Propose
+
+Use this skill only when the user explicitly asks to create an OpenSpec proposal for a project registered in Code Workspace.
+
+1. Resolve exactly one target project with `code-w project show "<project-name>" --json` and retain its `location`, `branch`, `type`, and `context` as the working boundary.
+2. Verify that target with `code-w project verify "<project-name>" --json`. If branch reconciliation is required, stop and use the Code Workspace branch-resolution workflow before creating a change.
+3. Change the working directory to the verified project location. Do not create the OpenSpec change in the Workspace registry directory.
+4. Follow the installed OpenSpec propose workflow in that project. Derive a kebab-case change name, create the change, and generate every artifact required for apply.
+5. Report the project name, change name, artifact paths, validation status, and whether the change is ready to implement.
+
+Do not modify `.code-workspace/`, do not broaden the request to other registered projects, and do not implement or archive the change unless the user asks.

package/extensions/openspec-workspace/1.0.0/artifacts/codex/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: code-workspace-openspec-propose
+description: Create an OpenSpec change for a selected Code Workspace project after resolving and verifying that project's registered scope.
+---
+
+# Code Workspace OpenSpec Propose
+
+Use this skill only when the user explicitly asks to create an OpenSpec proposal for a project registered in Code Workspace.
+
+1. Resolve exactly one target project with `code-w project show "<project-name>" --json` and retain its `location`, `branch`, `type`, and `context` as the working boundary.
+2. Verify that target with `code-w project verify "<project-name>" --json`. If branch reconciliation is required, stop and use the Code Workspace branch-resolution workflow before creating a change.
+3. Change the working directory to the verified project location. Do not create the OpenSpec change in the Workspace registry directory.
+4. Follow the installed OpenSpec propose workflow in that project. Derive a kebab-case change name, create the change, and generate every artifact required for apply.
+5. Report the project name, change name, artifact paths, validation status, and whether the change is ready to implement.
+
+Do not modify `.code-workspace/`, do not broaden the request to other registered projects, and do not implement or archive the change unless the user asks.

package/extensions/openspec-workspace/1.0.0/init.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+}
+
+function option(name) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : null;
+}
+
+try {
+  const contextFile = option("--context");
+  const outputRoot = option("--output");
+  const resultFile = option("--result");
+  if (!contextFile || !outputRoot || !resultFile) throw new Error("Usage: init.js --context <file> --output <directory> --result <file>");
+  const context = JSON.parse(fs.readFileSync(contextFile, "utf8"));
+  if (context.schemaVersion !== 1 || context.extensionSpecVersion !== 1 || context.extension?.id !== "openspec-workspace" || !Array.isArray(context.tools)) {
+    throw new Error("Invalid extension context");
+  }
+  const definitions = {
+    codex: {
+      id: "codex-propose-skill",
+      source: path.join(__dirname, "artifacts", "codex", "SKILL.md"),
+      target: ".codex/skills/code-workspace-openspec-propose/SKILL.md",
+    },
+    claude: {
+      id: "claude-propose-skill",
+      source: path.join(__dirname, "artifacts", "claude", "SKILL.md"),
+      target: ".claude/skills/code-workspace-openspec-propose/SKILL.md",
+    },
+  };
+  const outputs = [];
+  for (const tool of context.tools) {
+    const definition = definitions[tool];
+    if (!definition) continue;
+    const target = path.join(outputRoot, ...definition.target.split("/"));
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(definition.source, target);
+    outputs.push({ id: definition.id, source: definition.target });
+  }
+  fs.writeFileSync(resultFile, `${JSON.stringify({
+    schemaVersion: 1,
+    extensionSpecVersion: 1,
+    extension: { id: "openspec-workspace", version: "1.0.0" },
+    outputs,
+  }, null, 2)}\n`, { mode: 0o600 });
+} catch (error) {
+  fail(error.message);
+}