diff --git a/.claude/rules/GLOSSARY.md b/.claude/rules/GLOSSARY.md index 725ae58999e5..64fd130cfef5 100644 --- a/.claude/rules/GLOSSARY.md +++ b/.claude/rules/GLOSSARY.md @@ -16,6 +16,7 @@ - **输入语法分工(`/` vs `@`/`+`)**(用户拍板 2026-07-09 两轮:REQ-072 B 案立 v1,REQ-073 拍板修订 v2,**固化规则勿漂移**)— `/` = **显式执行一个动作**:命令 + 技能(技能的手动触发通道;技能另有模型按描述自动装载的路)+ MCP 生成命令 + 单条 `/agents` 管理入口;`@` 与 `+` = **装配本条消息**(同一统一弹窗的两个触发器):引用(指派子 agent / 引用文件)· 附加(文件、终端)· 模式(计划模式等主档切换)。**agent 不逐个平铺进 `/`**;**主档(build/plan)是"模式"、不进 Agent 引用节**;内部档(alpha-automation 系)任何弹窗不可见。一句话:斜杠回答"执行什么",@/+ 回答"这条消息怎么组装——让谁干、带上什么、用什么模式"。 - **command vs skill**(易混,与 Claude Code 心智一致)— **skill** = SKILL.md 能力包,模型可按描述**自动装载**,引擎同时为其生成同名 command 作显式入口;**command** = 纯模板展开,**只有**显式 `/name` 一条触发路。定制中心不单列 command tab(ADR-014 O2)。 +- **出厂技能(factory skills)基线 = 7 件**(REQ-082 盘点落档,2026-07-09;真源 = `factory-skills.ts:FACTORY_SKILL_IDS`,守卫 = `assert-seed-assets.sh`)— skill-creator(造技能)· agent-creator(造 agent)· customize-alpha(引擎配置/治理/定制中心约定)· integrate-project(外来 `.claude`/`.agents` 导入,ADR-024)· alpha-workspace(`~/Alpha` 目录契约,ADR-025)· cloud-dispatch(云派发契约/预算/数据边界,ADR-021)· office-docs(办公文档连接器选型 + xlsx 惯例 + PDF 缺口补位,REQ-080)。随 app 打包、经 `skills.paths` 直指随包资源(REQ-065 纯度通道,不落 `.alpha`);新增出厂技能三处同改:资源目录 + FACTORY_SKILL_IDS + seed 守卫。 ## 技术栈术语(opencode 侧,会在设计/实现里频繁出现) - **`@opencode-ai/sdk`** — 由 server OpenAPI 生成的 HTTP/SSE 客户端(v1 `/…` + v2 `/api/*`)。**前端与外部客户端访问后端的唯一稳定契约**。公开 MIT。 diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index 07652c79c4fc..9ed5d0e3f51e 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -65,9 +65,9 @@ | REQ-077 | Windows 正式构建通道:CI(GitHub 托管 windows runner)出含 win32 原生件的安装包 | feature | A | shipped(PR #167+#168) | **S36 shipped(2026-07-09,PR #167 + 修 #168;二跑 run 29001275508 全绿 = 验收①②实证:断言步证 win32 pty/watcher 在包内、artifact 127.7MB 可下载;首跑逮出 electron-builder v26 CI 隐式 publish 坑 → `--publish never`;verified 待验收③随 REQ-076 真机批;契约 [sprints/s36](sprints/2026-07-09-s36-req077-windows-ci/sprint.md))**:`alpha-windows-build.yml`(workflow_dispatch + windows-latest + bun 缓存 + ship:windows + **win32 原生件 pwsh 断言(缺即红)** + artifact 上传);机制核查 = 上游 sign-windows.ps1 无 Azure 密钥优雅自跳(无需加闸,且上游用 **Azure Trusted Signing** 可作 T3 采购先例)、bun 自动跑 pre 脚本(fresh runner 产物链完整);channel 为 choice 白名单输入(无注入面)。**S35 T1b 实测发现的补位(2026-07-09)**:bun 只装当前平台 optionalDeps → mac 交叉包缺 `node-pty-win32-x64`/`watcher-win32-x64` 等原生件,仅供内测/结构冒烟;正式包须 Windows 环境构建(上游 publish.yml 同款)。方案 = 自有 `.github/workflows/alpha-windows-build.yml`,**GitHub 托管 `windows-latest` 标准池**(不踩 Blacksmith 永久 queued 坑,docs/CI.md §5)+ `workflow_dispatch` 手动触发 + artifact 上传;签名/发版自动化归 REQ-076 T3 不抢跑。**REQ-076 真机批的用包前置**;验收 = 产物含 win32 原生件 + 真机可装(随真机批同场);详见 [requirements/REQ-077](requirements/REQ-077-windows-build-channel.md) | | REQ-078 | @/+ 装配弹窗诚实化与能力补齐:附件真通道(图片/PDF/文件)+「附加终端」文案失实修正 + 零查询钉「变更/最近文件」 | ux | A | shipped(PR #169;真机批残单 = session 表面像素/附件端到端真发送/拖拽 hover) | **S37 shipped(2026-07-09 当日,契约 [sprints/s37](sprints/2026-07-09-s37-req078-composer-popup/sprint.md),证据 [audits/s37](audits/2026-07-09-s37-req078/verify.md))**:T1/T2/T3 全量 + dev CDP 三图断言;**实施发现:上游 `/file/status` 恒返 [] 存根(SDK 有形引擎无实),T3 改走 `/vcs/status` 真实现**。原案:议题② + 弹窗审计实锤两处 placebo(C28):①「文件和文件夹」行两模式都送不进消息——home 未注册 `file.attach` 静默 no-op(composer-autocomplete.tsx:306-309),session 页选中文件落进隐藏的上游 prompt store、alpha 提交只发 text+mentions(alpha-composer.tsx:532-540)→ **附件被静默吞**;②「附加终端」desc 称「把终端输出带进上下文」,实际 `terminal.new` 只开终端 tab(composer-autocomplete-core.ts:170),引擎亦无终端→context 原语,且 home 上是死行。修序:T1 placebo 先行(附件行接真通道或先撤、终端行文案如实 + home 隐藏)→ T2 附件自建(引擎 `FilePartInput` 支持任意 mime+dataUrl 含图片/PDF,上游冻结 composer 粘贴/拖拽/原生选择器三通道可参照)→ T3 引用节零查询钉 git 变更文件(`file.status` 现成;上游有钉 open files 先例)+ `find.files` limit=8 放宽。后续 tier(另拍):行区间引用 `@path:12-40`(引擎吃 `?start=&end=`)、MCP 资源引用(`/experimental/resource`,NON_GOALS#4 须标注+fail-soft)、LSP 符号(`/find/symbol`);SubtaskPartInput 与 shell 模式明确暂缓(@agent 已覆盖指派心智;模式节语义已钉死);详见 [requirements/REQ-078](requirements/REQ-078-composer-popup-honesty.md) | | REQ-079 | 定制中心供给面 curation:Agent tab 撤下引擎原生内置 agent 平铺,浏览面只展示 catalog 精选可安装项 | ux | X | ready | **用户拍板方向(2026-07-09):「内置 agent 不需要显示,只提供必要的 agent/skill 让用户自己添加」**。现状(实查):Agent tab = 引擎 `app.agents()` 全量滤 hidden 后标「内置」平铺(use-extensions.ts:214-223、extension-hub.tsx:874)+ catalog 卡仅 2 条(code-reviewer/bug-triage);内部三 agent 已 hidden 不受影响;治理面板(governance-panel.tsx)已有原生 agent 的 hide/disable/override 管理入口 → **浏览面撤下原生平铺零功能损失**(管理职能归治理面板,浏览面回归「可安装的精选」)。连带 C 侧补充精选条目;「必要精选」残点见待拍板队列(不阻塞开工);详见 [requirements/REQ-079](requirements/REQ-079-hub-curation.md) | -| REQ-080 | 办公文档能力上架:xlsx/docx/pptx 写作 MCP 三连 + alpha 自写 office-docs 引导技能,office 套件收口 | feature | X | ready | **拍板(2026-07-09):①按推荐上架 ②office-docs 入出厂 ③paperjsx 留 watchlist** · 议题④(2026-07-09)+ 生态实查(GitHub/npm/pypi 逐项核验)**:Anthropic 官方四件(docx/pdf/pptx/xlsx)license 仍为 **Proprietary 禁再分发禁衍生**(anthropics/skills 逐 LICENSE.txt 核验,与 catalog `_disclaimers` 既有判断一致),且假定沙箱预装 LibreOffice/pandoc/python/node 四运行时 → Windows 小白不可行,上架红线维持;生态无可信 Apache/MIT 重实现;**Codex 已有官方 skills 体系**(developers.openai.com/codex/skills,较上次核查的新变化)但无官方文档技能。推荐上架(全 uvx/npx 运行时拉取 = 零再分发负担,单一 bootstrap 与现有 runtimeDep 预检模型匹配):① `excel-mcp-server`(uvx,MIT,4.0k★:创建/编辑/公式/图表/透视,免装 Excel,Windows 文档明示)② `Office-Word-MCP-Server`(uvx,MIT,2.1k★;详情页须如实标注其 PDF 转换工具需本机 MS Word)③ `Office-PowerPoint-MCP-Server`(uvx,MIT,32 工具);PDF 创建生态空缺(可信写 MCP 不存在)→ ④ alpha 自写 `office-docs` 引导技能补位(Apache-2.0:教连接器选型、xlsx 惯例、pypdf/reportlab 片段——底层库 BSD/MIT 可用,Anthropic 技能文本只可重表达不可抄);⑤ bundle:office 补齐(兑现条目内 `_verify` 既有意向:markitdown+filesystem+新三连+引导技能)。watchlist:`@paperjsx/mcp-server`(npx,MIT,全格式 JSON→doc 含 PDF 创建,0★/freemium 待熟)。选型三点已拍板(见上);C 侧上架 + A 侧引导技能随包;详见 [requirements/REQ-080](requirements/REQ-080-office-docs-suite.md) | +| REQ-080 | 办公文档能力上架:xlsx/docx/pptx 写作 MCP 三连 + alpha 自写 office-docs 引导技能,office 套件收口 | feature | X | in-sprint(S38;A 侧 office-docs 出厂技能 shipped PR #170,C 侧三连上架 + bundle:office 进行中) | **拍板(2026-07-09):①按推荐上架 ②office-docs 入出厂 ③paperjsx 留 watchlist** · 议题④(2026-07-09)+ 生态实查(GitHub/npm/pypi 逐项核验)**:Anthropic 官方四件(docx/pdf/pptx/xlsx)license 仍为 **Proprietary 禁再分发禁衍生**(anthropics/skills 逐 LICENSE.txt 核验,与 catalog `_disclaimers` 既有判断一致),且假定沙箱预装 LibreOffice/pandoc/python/node 四运行时 → Windows 小白不可行,上架红线维持;生态无可信 Apache/MIT 重实现;**Codex 已有官方 skills 体系**(developers.openai.com/codex/skills,较上次核查的新变化)但无官方文档技能。推荐上架(全 uvx/npx 运行时拉取 = 零再分发负担,单一 bootstrap 与现有 runtimeDep 预检模型匹配):① `excel-mcp-server`(uvx,MIT,4.0k★:创建/编辑/公式/图表/透视,免装 Excel,Windows 文档明示)② `Office-Word-MCP-Server`(uvx,MIT,2.1k★;详情页须如实标注其 PDF 转换工具需本机 MS Word)③ `Office-PowerPoint-MCP-Server`(uvx,MIT,32 工具);PDF 创建生态空缺(可信写 MCP 不存在)→ ④ alpha 自写 `office-docs` 引导技能补位(Apache-2.0:教连接器选型、xlsx 惯例、pypdf/reportlab 片段——底层库 BSD/MIT 可用,Anthropic 技能文本只可重表达不可抄);⑤ bundle:office 补齐(兑现条目内 `_verify` 既有意向:markitdown+filesystem+新三连+引导技能)。watchlist:`@paperjsx/mcp-server`(npx,MIT,全格式 JSON→doc 含 PDF 创建,0★/freemium 待熟)。选型三点已拍板(见上);C 侧上架 + A 侧引导技能随包;详见 [requirements/REQ-080](requirements/REQ-080-office-docs-suite.md) | | REQ-081 | 退役中国办公三件套:C 端 catalog 删 feishu/yuque/dingtalk 三连接器 + bundle:china-office | debt | C | **verified**(2026-07-09 当日执行:alpha-web PR #16 合入 + ECS 部署;线上端点实证 = v2026-07-09.1 / 24 条 / 三件套+套件全缺席 / bundle:office 完好 / A 内置公钥对新签名 verify=true。**部署插曲**:ECS→GitHub 当时完全不通(git 端点 000),按 deploy.sh 等价语义走 SSH 直推 git 对象 + reset + npm ci/build + systemd 重启 + 健康检查全绿;ECS root 补了 safe.directory 白名单,下次 deploy.sh 走 GitHub 不受影响) | **用户拍板(2026-07-09):「退役飞书等三件套,注释掉它们」——尚未想清楚如何优雅实现这些 MCP,先下架**。机制(实查):catalog schema 无 hidden/disabled 字段(catalog-types.ts:102-128),且旧 app 会忽略新增字段照常显示 → **「注释」不可行,唯一有效退役 = C 仓 catalog-src/catalog.json 删条目**(git 历史留档,想清楚后可随时重上架);流程 = 删 4 条目(3 连接器 + china-office 套件)+ bump version → build-catalog.mjs(sha256+ed25519 签名)→ deploy(联网用户下次打开 hub 即生效,**A 仓零动作**;A 内置快照禁手编、随下次发版 sync-catalog-snapshot.mjs 刷新,离线用户在此之前仍见旧条目 = ADR-023 已记录取舍)。连带回写:E2(dingtalk,shipped 半验)的「首次真调用待凭证」验收随退役作废;dingtalk 供应链 `_verify`(npm 无可审计公开源码)一并了结。**用户 GO(2026-07-09)——本日执行,回写见状态列** | -| REQ-082 | 内置技能基线补全:cloud-dispatch 云派发出厂技能(ADR-021 契约模板兑现)+ customize-alpha 增连接器/套件安装章节 | feature | A | ready | **用户拍板方向(2026-07-09):「云派发的应该也作为内置提供」;确认 ready 同日**。现状(实查):云派发教学 skill **从未建过**(ADR-021 §1「dispatch skill 的 contract 模板按此写死」为空头承诺,grep resources/ext/catalog 零命中);会话内仅当 `ALPHA_CLOUD_MCP_URL`+token 就位时注入 cloud_* MCP 工具(sidecar.ts:366-370),无任何使用指引。T1 = 新增出厂技能 `cloud-dispatch`(教 diff-only 契约、denied_paths 默认、预算/档位、回流落点 `.alpha/runs/`,ADR-021 数据边界如实声明;经 REQ-065 纯度通道 skills.paths 随包注入,不落 `.alpha`);T2 = customize-alpha 扩「连接器/套件」章节(hub 为主路径 + `alpha_register type=mcp` 项目级次路径 + 密钥/receipts 诚实边界)。**独立安装 skill 暂不立**(用户议题⑥的裁定建议):密钥采集在 main(`{file:}` 通道)、会话内安装绕过 receipts 账本、catalog 未向会话暴露——三个机制缺口补齐前独立 skill 只能半吊子,待「catalog-to-session + receipts 写路径」立项再议。基线盘点:现有出厂 5 件(skill-creator/agent-creator/customize-alpha/integrate-project/alpha-workspace)+ 本项 cloud-dispatch + REQ-080 office-docs = 7 件;详见 [requirements/REQ-082](requirements/REQ-082-builtin-skills-baseline.md) | +| REQ-082 | 内置技能基线补全:cloud-dispatch 云派发出厂技能(ADR-021 契约模板兑现)+ customize-alpha 增连接器/套件安装章节 | feature | A | shipped(PR #170;真机批残单 = 登录态会话真派发一单 research + 登出态诚实引导实测) | **S38 shipped(2026-07-09 当日,契约 [sprints/s38](sprints/2026-07-09-s38-supply-baseline/sprint.md))**:cloud-dispatch 文案逐项对照 B 侧源码写成(cloud-mcp.ts 八工具 / cloud-contract.ts 预算默认 25·300k·600s 帽 50·500k·1800s / pipelines.ts 七 kind 与 input 字段 / schedules.ts 熔断 3),零想象接口;customize-alpha 连接器/套件章 + GLOSSARY 出厂 7 件基线落档 + seed 守卫收全量(存量 3 件历史漏登一并补)。原案:**用户拍板方向(2026-07-09):「云派发的应该也作为内置提供」;确认 ready 同日**。现状(实查):云派发教学 skill **从未建过**(ADR-021 §1「dispatch skill 的 contract 模板按此写死」为空头承诺,grep resources/ext/catalog 零命中);会话内仅当 `ALPHA_CLOUD_MCP_URL`+token 就位时注入 cloud_* MCP 工具(sidecar.ts:366-370),无任何使用指引。T1 = 新增出厂技能 `cloud-dispatch`(教 diff-only 契约、denied_paths 默认、预算/档位、回流落点 `.alpha/runs/`,ADR-021 数据边界如实声明;经 REQ-065 纯度通道 skills.paths 随包注入,不落 `.alpha`);T2 = customize-alpha 扩「连接器/套件」章节(hub 为主路径 + `alpha_register type=mcp` 项目级次路径 + 密钥/receipts 诚实边界)。**独立安装 skill 暂不立**(用户议题⑥的裁定建议):密钥采集在 main(`{file:}` 通道)、会话内安装绕过 receipts 账本、catalog 未向会话暴露——三个机制缺口补齐前独立 skill 只能半吊子,待「catalog-to-session + receipts 写路径」立项再议。基线盘点:现有出厂 5 件(skill-creator/agent-creator/customize-alpha/integrate-project/alpha-workspace)+ 本项 cloud-dispatch + REQ-080 office-docs = 7 件;详见 [requirements/REQ-082](requirements/REQ-082-builtin-skills-baseline.md) | ## Active — P2(债务) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index e81fc5571af3..75185f20dc37 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -6,6 +6,9 @@ ## [Unreleased] ### Added +- **新增出厂技能「cloud-dispatch」:会话里就能把任务派到云上跑**(REQ-082,需下个签名版本生效)——登录(代付)状态下,让 agent「云端调研一下 X」即可正确派发:技能教会模型云任务的完整契约(调研/代码审查/文档三类管线与沙箱档、预算上限、结果取回),并内置数据边界纪律(代码只送 diff、绝不带密钥/.env)。未登录或 BYOK 时如实告知云派发不可用并指路登录,不会假装派发。 +- **新增出厂技能「office-docs」:做表格/写文档/生成 PPT 有了正确指路**(REQ-080,需下个签名版本生效)——问「帮我做个 Excel」时模型知道该用哪个连接器(读文档=markitdown、写 xlsx/docx/pptx=对应办公连接器)、没装时指路扩展市场一键安装(或征得同意后用本地 Python 脚本兜底)、内置表格制作惯例(真实数字/日期类型、表头冻结、公式而非写死数值)与 PDF 生成代码片段(生态没有可信的 PDF 写连接器,如实补位不硬装)。 +- **customize-alpha 技能补上连接器/套件章节**(REQ-082)——会话里问「怎么装连接器」不再只会指路定制中心:密钥为什么要走安装弹窗(密文存储,绝不明文写配置)、项目级注册的信任门语义、首跑下载慢是诚实状态、套件与插件的区别,一次讲清。 - **输入框支持真·附件:图片与 PDF(粘贴 / 拖拽 / 选择器三通道)**(REQ-078,需下个签名版本生效)——@/+ 弹窗「添加附件」现在打开真正的文件选择器;截图可直接粘贴进输入框、文件可拖进来,附件以缩略图标签展示、可单个移除,随消息真实发给模型。不支持的类型(文本/代码文件)与超限(图片 5MB / PDF 10MB)会如实提示原因并指路 @ 引用,绝不静默丢弃——此前弹窗里的「文件和文件夹」选了文件其实**发不出去**(首页点击无反应、会话页选中的文件被静默吞掉),本次一并根治。 - **@ 弹窗打开即看到本项目的改动文件**(REQ-078,需下个签名版本生效)——不输入关键词时「文件」节自动钉出 git 变更文件(最多 10 条,点击即引用);输入关键词照常全项目搜索,且搜索结果上限从 8 条放宽到 20 条。 diff --git a/docs/requirements/REQ-080-office-docs-suite.md b/docs/requirements/REQ-080-office-docs-suite.md index 9a6a8c17c65a..84cc64caaeb5 100644 --- a/docs/requirements/REQ-080-office-docs-suite.md +++ b/docs/requirements/REQ-080-office-docs-suite.md @@ -5,7 +5,7 @@ type: feature priority: P1 repo: X created: 2026-07-09 -status: ready +status: in-sprint source: 用户议题④(2026-07-09)+ 生态实查;用户拍板(2026-07-09):①按推荐上架 ②office-docs 引导技能入出厂内置 --- diff --git a/docs/requirements/REQ-082-builtin-skills-baseline.md b/docs/requirements/REQ-082-builtin-skills-baseline.md index 977727303a9c..4e86df2ed86f 100644 --- a/docs/requirements/REQ-082-builtin-skills-baseline.md +++ b/docs/requirements/REQ-082-builtin-skills-baseline.md @@ -5,7 +5,7 @@ type: feature priority: P1 repo: A created: 2026-07-09 -status: ready +status: shipped source: 用户拍板方向(2026-07-09):「云派发的应该也作为内置提供」;议题⑥裁定 = 扩 customize-alpha 章节、独立安装 skill 暂不立 --- diff --git a/docs/sprints/2026-07-09-s38-supply-baseline/sprint.md b/docs/sprints/2026-07-09-s38-supply-baseline/sprint.md new file mode 100644 index 000000000000..74427ec8fa8c --- /dev/null +++ b/docs/sprints/2026-07-09-s38-supply-baseline/sprint.md @@ -0,0 +1,42 @@ +# S38 — 供给面基线批:内置技能补全 + 办公三连上架 + hub curation(2026-07-09) + +> 契约(ADR-018):目标 / 抽取 IDs / task 表 / gates / 结果 / 回写清单。 + +## 目标 + +把「开箱供给面」补齐到拍板基线:云派发与办公文档两件出厂技能(7 件基线成形)、办公 MCP 三连上架(C 侧)、定制中心浏览面回归「可安装的精选」(撤引擎原生 agent 平铺)。 + +## 抽取 + +| ID | 仓 | 状态入 | 状态出 | +|---|---|---|---| +| REQ-082 | A | ready | — | +| REQ-080 | X(A+C) | ready | — | +| REQ-079 | X(A+C) | ready | — | + +## Tasks + +- [x] T1(REQ-082)出厂技能 `cloud-dispatch`:SKILL.md(工具面/信封契约/预算档位/数据边界/前置如实声明,全部按 B 侧 cloud-mcp.ts + cloud-contract.ts 实况写)+ factory-skills.ts 登记 + seed 守卫 + 测试(PR #170) +- [x] T2(REQ-082)customize-alpha 扩「连接器/套件」章节(hub 主路径 + `alpha_register type=mcp` 次路径 + 密钥 `{file:}`/receipts 诚实边界 + uvx/npx runtimeDep);出厂技能 7 件基线写入 GLOSSARY(PR #170) +- [x] T3(REQ-080 A)出厂技能 `office-docs`:连接器选型 + xlsx 惯例(自写重表达,零 Anthropic 文本)+ PDF 缺口 pypdf/reportlab 引导 + 登记/守卫/测试(PR #170) +- [ ] T4(REQ-080 C)alpha-web catalog 增 3 条 mcp(excel-mcp-server / office-word-mcp-server / office-powerpoint-mcp-server,钉版 + runtimeDep=uv + word→PDF 需本机 Word 如实标注)+ bundle:office 补齐 + version bump → build-catalog → PR → 部署 → 线上验证 +- [ ] T5(REQ-079)Agent tab 浏览面撤引擎原生 agent 平铺(搜索面同口径;治理面板管理入口不动);精选清单提案(删减/补充)写本档「提案」节交拍板 +- [ ] T6 单测 + alpha-check 全绿;CDP 截图核验(Agent tab 前后 + 技能就位) + +## Gates + +- [ ] alpha-check(北极星守卫 + typecheck + 单测)全绿 +- [ ] 零改上游文件 +- [ ] office-docs 技能 license 审查:零 Anthropic 技能文本抄袭(仅 BSD/MIT 底层库引用) +- [ ] cloud-dispatch 技能文案与 B 侧 schema 零矛盾(工具名/字段/预算帽逐项对照) + +## 精选清单提案(REQ-079 残点,交拍板) + +见本目录 `curation-proposal.md`(开工提案,不阻塞本批实现)。 + +## 回写清单 + +- [ ] BACKLOG REQ-082/080/079 → shipped(PR 号) +- [ ] CHANGELOG [Unreleased] 用户可见条目 +- [ ] 三份需求档 frontmatter 同步 +- [ ] 证据:audits/2026-07-09-s38-supply-baseline/ diff --git a/packages/ui-mac/resources/factory-skills/cloud-dispatch/SKILL.md b/packages/ui-mac/resources/factory-skills/cloud-dispatch/SKILL.md new file mode 100644 index 000000000000..d7b75ae16a20 --- /dev/null +++ b/packages/ui-mac/resources/factory-skills/cloud-dispatch/SKILL.md @@ -0,0 +1,96 @@ +--- +name: cloud-dispatch +description: Dispatch tasks to the alpha-code cloud platform (research, code review, docs, sandboxed office/data/code jobs) and fetch their results. Use when the user asks to run something "in the cloud" (云端/云上跑), offload a long research or analysis task, review a diff server-side, or create/list/delete a scheduled cloud job. +license: MIT (alpha-code original) +--- + +# Cloud dispatch + +You dispatch bounded jobs to the alpha-code cloud platform and bring results back. The cloud +tools come from the **`cloud` connector** — in your tool list they carry its prefix (search your +tools for `cloud_`): dispatch, status, await, artifacts, schedule_create / schedule_list / +schedule_delete, web_search. + +## Availability — check first, never pretend + +The cloud connector is only wired when the user is **logged in with platform-pays** (登录即代付). +If no `cloud_*` tools appear in your tool list: + +- say so honestly — cloud dispatch is not available right now; +- guide the user to log in from the account menu (BYOK-only and logged-out sessions have model + access but **no** cloud dispatch); +- do NOT simulate a dispatch or fabricate results. + +## Data boundary — read before any dispatch (ADR-021) + +Everything you put in an envelope **leaves the user's machine**. Rules: + +1. **Diff-only for code.** Never send a whole repository or directory. For code-review, send the + relevant `git diff` output only (the pipeline truncates around ~12k chars anyway). +2. **No secrets.** Never include contents of `.env*`, `*.pem`, key files, tokens, or anything from + `.alpha/` or `.git/`. If a diff contains a credential, redact it and tell the user. +3. Dispatches from the Extension Hub additionally pass a hard local guard (1MB envelope cap + + secrets scan). Session dispatches through these tools rely on server-side schema validation + plus **your** discipline — the two rules above are on you. + +## The envelope (`cloud_dispatch`) + +Two autonomy modes: + +- `autonomy: "pipeline"` — fixed server-side pipeline; requires `kind` + `input`. +- `autonomy: "bounded-agent"` — requires `objective` (+ optional `capabilities`). Heavier; prefer + a pipeline when one fits. + +Pipeline kinds and their `input`: + +| kind | input | notes | +|---|---|---| +| `research` | `{question, search?: "native"\|"tavily"\|"brave"}` | web-grounded research with citations | +| `code-review` | `{diff}` | diff-only (see boundary above) | +| `docs` | `{code, type?: "readme"\|…}` | doc generation from code | +| `office-report` | sandboxed | produces .docx/.pptx/.xlsx artifacts | +| `data-analysis` | sandboxed | pandas/matplotlib → charts + report | +| `bugfix` / `migration` | sandboxed | patch/refactor pipelines | + +Budget (optional, but set it explicitly for anything nontrivial): +`budget: {max_iter?, max_tokens?, max_wall_clock_sec?}` — defaults 25 iterations / 300k tokens / +600s; hard caps 50 / 500k / 1800s. These are enforced server-side per job. + +Example — research dispatch: + +```json +{ + "autonomy": "pipeline", + "kind": "research", + "input": { "question": "…the user's question, self-contained…" }, + "budget": { "max_tokens": 150000, "max_wall_clock_sec": 300 } +} +``` + +## Workflow + +1. `cloud_dispatch` → returns `{job_id, status: "queued"}` (schema-invalid envelopes are rejected + with details — fix and retry, don't loop blindly). +2. `cloud_await` with the `job_id` — it polls **at most ~25s per call**; for longer jobs call it + again (or `cloud_status` for a single snapshot). Terminal states: `completed` / `failed` / + `cancelled`. +3. `cloud_artifacts` — lists artifact ids + the inline result. Present the result to the user; + if they want it as a file, write it to disk yourself (their stated path, the current project, + or `~/Alpha` conventions when no project applies). + +Honest reporting: if a job fails or times out, relay the actual status and error — never +summarize a failed job as if it produced results. + +## Schedules (recurring cloud jobs) + +`cloud_schedule_create {name, cron, tz?, envelope, enabled?}` — the envelope is a normal dispatch +envelope. Limits: minimum interval 5 minutes, max 10 schedules per tenant, tighter budget caps +than one-off jobs. `cloud_schedule_list` shows next fire time and breaker state (3 consecutive +failures trips a breaker); `cloud_schedule_delete {schedule_id}` stops future fires. Runs fired +by schedules are pulled back into the project's `.alpha/runs/` on app launch. + +## Where records live + +- Hub- and schedule-originated runs leave local audit records under `/.alpha/runs//`. +- Session dispatches (these tools) return results inline — nothing is written to disk unless you + write it. `.alpha/` itself is engine/harness territory; don't create files there. diff --git a/packages/ui-mac/resources/factory-skills/customize-alpha/SKILL.md b/packages/ui-mac/resources/factory-skills/customize-alpha/SKILL.md index e7c592aa17f5..9be5a604c065 100644 --- a/packages/ui-mac/resources/factory-skills/customize-alpha/SKILL.md +++ b/packages/ui-mac/resources/factory-skills/customize-alpha/SKILL.md @@ -37,6 +37,24 @@ the app and never appears in `.alpha`. 3. **Creating new skills/agents** — delegate to the factory skills `skill-creator` / `agent-creator` (they interview, generate, write to the right place, and hot-reload). +## Connectors (MCP) and bundles + +- **Primary path = Extension Hub (定制中心)**: browse the curated catalog, one-click install with + dependency preflight (`uv` / `node` checked before install), API keys collected as masked input + and stored as `{file:}` references — **never write a connector API key in plaintext into + `alpha.jsonc` yourself**; if a connector needs a key, send the user to the Hub install flow. +- **Project-scoped secondary path** = `alpha_register type=mcp` (config goes to + `/.alpha/alpha.jsonc`): executable connectors only load after the user grants the + per-project trust dialog — expect that, don't call it a failure. +- **Runtime note**: catalog connectors run via `uvx`/`npx` pinned versions; first launch downloads + from PyPI/npm and can be slow or blocked on restricted networks. A just-installed connector may + show "connecting" for a while — that is honest state, not an error. +- **Bundles (套件)** are alpha's install manifests: one click fans out into several atomic installs + (MCP + skills + plugins), each with its own receipt and uninstall. A bundle is not an engine + plugin (插件 = JS module with hooks; it cannot contain skills/agents). +- The Hub's install ledger (receipts) is what makes 「已安装」 accurate — installs done by editing + config by hand won't show there; prefer the Hub or `alpha_register` so state stays visible. + ## Governing built-ins The Extension Hub's governance panel (已安装 → 内置) can hide or disable upstream built-in agents diff --git a/packages/ui-mac/resources/factory-skills/office-docs/SKILL.md b/packages/ui-mac/resources/factory-skills/office-docs/SKILL.md new file mode 100644 index 000000000000..d2a73bf19201 --- /dev/null +++ b/packages/ui-mac/resources/factory-skills/office-docs/SKILL.md @@ -0,0 +1,90 @@ +--- +name: office-docs +description: Create, edit, and read office documents — Excel (xlsx), Word (docx), PowerPoint (pptx), and PDF. Use when the user asks to build a spreadsheet, write a report or slide deck as a real document file, extract content from office files, or generate/merge/split PDFs. +license: Apache-2.0 (alpha-code original — no Anthropic skill text) +--- + +# Office documents + +You help the user produce and read real office files. alpha-code's office capability is built on +**connectors (MCP)** — pick the right one, and be honest when it isn't installed. + +## Which tool for which job + +| Job | Use | Notes | +|---|---|---| +| **Read/extract** any document (PDF/Word/PPT/Excel/HTML/images) | markitdown connector (`convert_to_markdown`) | read-only, converts to Markdown | +| **Create/edit xlsx** | excel-mcp-server connector | formulas, charts, pivot tables; no Excel install needed (openpyxl-based) | +| **Create/edit docx** | office-word-mcp-server connector | styles, tables, footnotes; its *PDF-export tool alone* requires local Microsoft Word — the rest works everywhere | +| **Create/edit pptx** | office-powerpoint-mcp-server connector | slide creation/editing, template-preserving | +| **Create/merge/split PDF** | no trusted connector exists (ecosystem gap) | write a small Python script with `reportlab` / `pypdf` (see below) | + +All three writer connectors run via `uvx` (Python fetched at first run) — they work the same on +macOS and Windows, and none of them needs Microsoft Office installed (single exception noted +above). + +## If the connector is not installed + +Check your tool list first. If the needed tools are absent: + +1. Point the user to the **Extension Hub (定制中心) → 连接器 → 办公**, or the 办公套件 bundle, + for one-click install (first run downloads from PyPI — may take a minute). +2. As a fallback — only with the user's consent to run code — write a local Python script using + the same underlying libraries: `openpyxl` (xlsx), `python-docx` (docx), `python-pptx` (pptx). + These are BSD/MIT-licensed and installable with `uv pip` / `pip`. +3. Never fake success: if you can neither use a connector nor run code, say exactly that. + +## Spreadsheet conventions (xlsx) + +When you build workbooks, default to these habits unless the user says otherwise: + +- One logical table per sheet; row 1 is the header row; give sheets meaningful names. +- Store real types: numbers as numbers, dates as dates — not preformatted strings. Apply number + formats (currency, percent, date) via cell format, not by baking text. +- Don't merge cells inside a data range (it breaks sorting/filtering); merging is fine for titles + above the table. +- Use formulas (`=SUM(...)` etc.) rather than precomputed constants when the sheet is meant to be + edited later; recompute totals when source cells change. +- Charts and pivots should reference ranges, so they update when data changes. +- For large data dumps, freeze the header row and add an autofilter. + +## PDF creation/manipulation snippets + +Create a simple PDF report (`reportlab`, BSD): + +```python +from reportlab.lib.pagesizes import A4 +from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer +from reportlab.lib.styles import getSampleStyleSheet + +styles = getSampleStyleSheet() +doc = SimpleDocTemplate("report.pdf", pagesize=A4) +doc.build([ + Paragraph("Title", styles["Title"]), + Spacer(1, 12), + Paragraph("Body text …", styles["BodyText"]), +]) +``` + +Merge / split / extract pages (`pypdf`, BSD): + +```python +from pypdf import PdfReader, PdfWriter + +w = PdfWriter() +for src in ("a.pdf", "b.pdf"): + for page in PdfReader(src).pages: + w.add_page(page) +with open("merged.pdf", "wb") as f: + w.write(f) +``` + +For "document → PDF" requests, prefer generating the document (docx/xlsx) first, then ask how the +user wants the PDF: local Word conversion (Windows + Word only), printing to PDF manually, or a +reportlab re-render — each has different fidelity; don't silently pick one. + +## Output location + +Write files where the user says; in a project, prefer the project directory. With no project +context, follow the `~/Alpha` workspace conventions (deliverables are user-visible files — never +write into `.alpha/`). diff --git a/packages/ui-mac/src/main/factory-skills.ts b/packages/ui-mac/src/main/factory-skills.ts index 0bd10cd565d7..6344243b8693 100644 --- a/packages/ui-mac/src/main/factory-skills.ts +++ b/packages/ui-mac/src/main/factory-skills.ts @@ -26,7 +26,15 @@ import { join, sep } from "node:path" import { opencodeHomeDir } from "./alpha-bridge" import { alphaGlobalRoot } from "./alpha-installs" -export const FACTORY_SKILL_IDS = ["skill-creator", "agent-creator", "customize-alpha", "integrate-project", "alpha-workspace"] as const +export const FACTORY_SKILL_IDS = [ + "skill-creator", + "agent-creator", + "customize-alpha", + "integrate-project", + "alpha-workspace", + "cloud-dispatch", + "office-docs", +] as const export function factorySkillsEnabled(): boolean { return process.env.ALPHA_FACTORY_SKILLS_DISABLE !== "1" @@ -48,6 +56,10 @@ export function factorySkillSources(input: { "integrate-project": join(root, "factory-skills", "integrate-project"), // REQ-071/ADR-025:~/Alpha 目录契约(Journal/Memory/Outputs)的写入约定载体 "alpha-workspace": join(root, "factory-skills", "alpha-workspace"), + // REQ-082:云派发教学(ADR-021 契约模板兑现;工具面/预算帽按 B 侧 cloud-mcp 实况,登出态文案如实) + "cloud-dispatch": join(root, "factory-skills", "cloud-dispatch"), + // REQ-080:办公文档引导(连接器选型 + xlsx 惯例自写重表达 + PDF 缺口 pypdf/reportlab 补位) + "office-docs": join(root, "factory-skills", "office-docs"), } } diff --git a/scripts/assert-seed-assets.sh b/scripts/assert-seed-assets.sh index 6dee1067d622..053230f3e037 100755 --- a/scripts/assert-seed-assets.sh +++ b/scripts/assert-seed-assets.sh @@ -26,7 +26,10 @@ need_dir() { { [ -d "$1" ] && [ -n "$(ls -A "$1" 2>/dev/null)" ]; } || miss "$1" need_dir "$res/skills" # builtin skills (installable via 定制中心) need_file "$res/skills/skill-creator/SKILL.md" # REQ-036 出厂技能(skills.paths 原位引用) -need_file "$res/factory-skills/agent-creator/SKILL.md" # REQ-036 出厂技能(alpha 自写) +# 出厂技能基线(REQ-082 时点 = 7 件,与 factory-skills.ts FACTORY_SKILL_IDS 一致;skill-creator 在上面) +for fs in agent-creator customize-alpha integrate-project alpha-workspace cloud-dispatch office-docs; do + need_file "$res/factory-skills/$fs/SKILL.md" +done need_file "$res/agents/code-reviewer.md" # REQ-023 vendored agent (zero-network install) need_dir "$res/plugins/opencode-notify" # REQ-023 vendored plugin (self-contained JS) need_file "$res/NOTICE.txt" # B15 MIT / third-party attribution — license compliance