Imported from yangfanfengshun/SpecWeaver (
AGENTS.md). Install upstream withnpx skills add yangfanfengshun/SpecWeaver. Copyright stays with the author.
SpecWeaver Agent 指南
你正在处理什么
当前目录是 SpecWeaver 插件根目录,不是普通业务项目。SpecWeaver 把 Tower、 蓝湖和 Eolink 中分散的需求上下文整理为可追溯资料,并提供受控的 Git 提交流程。
插件支持 Codex、Claude Code 和 Cursor。平台清单、Skill、MCP 与运行脚本均以 当前目录为根;不要假设它们位于外层开发仓库中。
本文件是 Codex 在 SpecWeaver 仓库目录中工作时读取的仓库级说明。插件安装后的
运行流程仍以各 Skill 的 SKILL.md 为准;不要把本文件复制到用户业务项目。
组件职责
skills/configure-specweaver/:配置认证和验证数据源连接;skills/requirement-collection/:处理需求模式和范围,调用统一脚本收集来源;skills/requirement-analysis/:完整收集成功后默认分析已收集来源并生成requirement.md;skills/tower-source-collection/、skills/lanhu-source-collection/、skills/eolink-source-collection/:分别读取平台事实并返回统一来源结果;skills/lanhu-design-implementation/:开发时主动发现设计上下文并按需查询精确 视觉事实;skills/daily-report/:把当前任务的已完成事项写入共享日志,或汇总当天跨项目日报;skills/tower-requirement-collection/:仅保留旧 Skill 名称兼容入口;skills/git-commit/:审查、验证和提交明确范围的 Git 改动;mcp/tower/:Tower 任务读取和经确认的评论发布;mcp/eolink/:Eolink 项目与 API 读取;mcp/lanhu/:蓝湖认证、设计列表、规范化图层树、预览图与切图读取;mcp/requirements/:确定性编排 Tower、蓝湖和 Eolink 完整来源收集与验证;scripts/:MCP 启动、本地认证配置和specweaver终端命令。
Skill 定义工作流,MCP 提供数据能力。不要绕过 Skill 自行拼接流程,也不要把 MCP 返回结果当作已经确认的需求结论。
Codex 首次安装与日常维护
当用户要求在 Codex 中安装 SpecWeaver 时,按“环境检查 → 添加 marketplace → 安装插件 → 提示独立配置命令 → 新任务加载 → 首次使用验证”的顺序处理。安装与 配置是两个独立阶段,不能把插件已经下载描述成数据源已经可用。
1. 安装前检查
先确认 Git、Codex 和 uv 可用:
git --version
codex --version
uv --version
插件支持 macOS 和 Linux;Windows 建议在 WSL 中使用。安装源是公开 GitHub 仓库,
统一安装器会自行管理 ~/.specweaver/runtime,不需要访问 SpecWeaver 的开发仓库。
若 uv 不存在,先引导用户按官方方式安装并重新打开终端。不要通过修改插件缓存、
伪造可执行文件或跳过 MCP 依赖来绕过检查。
2. 首次安装
Codex 用户推荐在普通终端执行一条命令:
curl -fsSL https://raw.githubusercontent.com/yangfanfengshun/SpecWeaver/master/install.sh | bash -s -- --codex
该命令安装或复用 Codex 中的 specweaver@specweaver,将公共终端入口指向
~/.specweaver/runtime,但不会自动进入认证配置。安装结束后在普通终端运行
specweaver configure。
用户明确要求同时安装本机已存在的多个 AI 宿主时,省略 --codex:
curl -fsSL https://raw.githubusercontent.com/yangfanfengshun/SpecWeaver/master/install.sh | bash
现有手动安装方式继续作为单平台安装和故障恢复入口,下面的代码块可以整段复制:
codex plugin marketplace add yangfanfengshun/SpecWeaver && \
codex plugin add specweaver@specweaver && \
~/.codex/plugins/cache/specweaver/specweaver/0.8.1/scripts/setup.sh --install-cli
specweaver@specweaver 的前半部分是插件 ID,后半部分是 marketplace 名称。
setup.sh --install-cli 只安装 specweaver 终端入口。插件升级时使用新版本号
对应的缓存路径,认证配置始终另行运行。
上述缓存路径已在 macOS 验证;Windows 路径尚未验证。Windows 用户可以按实际缓存 位置调整命令,或者回到 Codex App 发送“配置 SpecWeaver”,由 AI 定位插件并启动 配置。
specweaver configure 先显示平台多选菜单。Tower 和蓝湖输入账号与不回显的密码并
立即验证登录,成功后保存 Cookie;Eolink 只保存,第一次读取真实资源时再验证。
Tower 或蓝湖要求人工验证时,按提示的配置文件路径填写对应 Cookie,或使用
specweaver configure <platform> --cookie。
若当前 Codex 客户端提供插件目录或专用插件管理工具,优先使用该界面或工具完成 同一安装动作;不要为了绕过宿主权限策略而强制改用终端。
3. 加载插件
首次安装和配置完成后,新建一个 Codex Agent 任务。插件 Skills 和 MCP 工具以新任务 为安全加载边界;不要在旧任务中仅凭安装命令成功就声称新版本已经生效。
如果宿主明确要求重启或重新加载,先完成对应操作,再创建新任务。
4. 验证安装
先确认 marketplace 中能看到插件:
codex plugin list --marketplace specweaver
再让用户提供一个自己有权访问的 Tower 任务链接,并按正常需求收集流程读取。能够
触发 requirement-collection、调用 Tower MCP、生成缓存并返回真实任务摘要,才说明
插件、Skill、MCP 和认证链路均已正常工作。
更新已有安装
首次安装闭环完成后,只有用户明确要求升级或排查版本时才进入本节。先刷新 runtime、marketplace 和插件:
specweaver update --codex
specweaver status
specweaver update 不覆盖 ~/.specweaver/.env,runtime 存在本地修改时停止,
不会强行覆盖。更新完成后新建 Codex Agent 任务。
没有使用统一安装入口时,继续使用原生命令:
codex plugin marketplace upgrade specweaver
codex plugin add specweaver@specweaver
插件使用显式 SemVer。不要直接修改 ~/.codex/plugins/cache 中的 plugin.json
或复制文件覆盖缓存来制造更新结果。更新后使用新版本缓存中的
scripts/setup.sh --install-cli,让终端入口指向新版本,然后新建 Codex Agent
任务。
日后更新认证或检查连接
specweaver configure tower
specweaver configure eolink
specweaver configure lanhu
specweaver check
不带平台名的 specweaver configure 先显示平台多选菜单;带平台名时直接进入该
平台。Tower、Eolink 或蓝湖单独失效时,不得让用户重填其他平台。
安装故障处理
- marketplace 找不到:执行
codex plugin marketplace upgrade specweaver后重试; - 插件已安装但 Skill 或 MCP 未出现:新建 Agent 任务,必要时重启宿主;
- MCP 启动失败:确认
uv --version正常,并检查宿主提供的 MCP 状态与错误信息; - 认证失败:不要重复安装插件,运行对应的
specweaver configure <platform>; - 更新后仍是旧版本:核对
codex plugin list --marketplace specweaver,重新刷新 marketplace 并安装,不直接编辑插件缓存。
执行安装或更新前,应向用户说明会修改其 Codex marketplace 和插件配置;命令失败 时报告实际错误,不得把 marketplace 已添加、插件已下载或宿主待重载说成安装完成。
处理用户请求
配置与认证
用户要求安装后初始化、配置、重新配置、更新 Cookie 或密码、检查连接时,使用
configure-specweaver Skill。
- 认证信息只通过终端输入,密码不回显,允许用户按平台选择配置;
- 不要求用户在对话中粘贴 Cookie、密码或 Token;
- 不读取、展示或总结
~/.specweaver/.env; - 配置失败时区分未配置、能力关闭、已配置待首次使用验证、登录失效、无权限和 网络错误;
- 只更新失败平台,不重新收集其他平台的凭据;
- 不把 Tower 任务链接或蓝湖项目链接作为安装配置的必填项。
Tower 任务
用户提供 Tower 任务链接或要求分析 Bug、整理需求、补齐设计/API 上下文时,使用
requirement-collection Skill。完整模式只调用统一 requirement_collect 工具,
不由 Agent 拼接三个来源 MCP。
- 只有明确
BugTag 时直接进行快速分析,在对话中输出,不创建资料文件; - Tower 预读必须同时缓存正文和全部评论里的普通图片;快速分析必须查看全部缓存图片, 缓存失败时明确报告缺失证据;
- 普通需求意图不明确时先询问快速分析或完整收集并分析;只有选择完整路线后才读取并 展示蓝湖和 Eolink 候选;
- 完整模式必须先确认设计稿、API 范围和输出目录,再由统一脚本写入来源文件;
- 完整收集为
success时直接使用requirement-analysis生成requirement.md, 不再二次询问;用户此前明确只收集时停止,partial时暂停; - 只记录可追溯事实,不虚构缺失的设计、接口或验收条件;
- 数据源认证失败时暂停依赖步骤,让用户重配或明确选择降级。
用户明确要求按已收集需求开发或还原带蓝湖设计的页面时,使用
lanhu-design-implementation。先通过 Tower URL 与项目目录定位用户缓存中的收集
清单并查看项目预览图,再按组件、节点或区域查询缓存中的结构化设计事实;不要要求
用户重复提供已保存的蓝湖链接。
日报整理
用户说“整理一下日报”“把本次工作加入日报”“整理今天日报”或“汇总今日工作”时,
使用 daily-report Skill。
- 记录模式只提取当前项目名称和已有完成证据的事项,写入
~/.specweaver/daily-logs/YYYY-MM-DD.md; - 汇总模式读取当天全部项目记录,在对话中输出合并后的日报,不重复写回日志;
- 不记录进行中事项、问题、明日计划、对话全文、私有链接或认证信息;
- 只有用户明确触发才记录,不能假装遗忘的任务已经自动进入日报。
Git 提交
用户明确要求提交、生成提交信息、按 Tower 需求提交或同步提交信息到 Tower 时,
使用 git-commit Skill。
- 只处理用户明确授权范围内的改动;
- 提交前完成必要验证;
- 使用 Conventional Commits;
- Tower 评论先预览,用户确认后才发布;
- 不自动推送、创建 PR、合并或发布版本。
文件与输出边界
- 需求资料写入用户当前项目约定的位置,不写入插件安装目录;
- 不修改用户代码,除非用户明确要求进入开发实施;
- 不把快速分析升级成完整资料收集;
- 不在缺少确认时下载多组设计稿或 API;
- 不把私有链接、认证信息和登录响应写入公开文档、提交或日志;
- 不编辑平台缓存中的插件副本来“永久修复”问题。
读取顺序
- 根据用户意图选择匹配的 Skill;
- 完整读取该 Skill 的
SKILL.md; - 只按 Skill 指向读取必要引用资料;
- 调用对应 MCP;
- 明确区分数据源事实、推断和用户决策;
- 按 Skill 的完成条件验证输出。
如果没有 Skill 覆盖请求,说明插件不提供该流程,再使用宿主 Agent 的常规能力。 不要假装 SpecWeaver 已经执行了不具备的操作。
安全规则
- 绝不输出 Cookie、密码、Token、
.env内容或完整登录响应; - 绝不把认证信息提交到 Git;
- 绝不在未确认时向 Tower 写评论;
- 绝不伪造 Tower、蓝湖或 Eolink 返回内容;
- 绝不覆盖、删除或强推已发布 tag;
- 外部写操作失败时说明实际状态,不声称成功。
修改插件本身时
若用户明确要求开发或修复 SpecWeaver:
- 保持三平台的版本和核心描述一致;
- 保持清单路径相对于插件根目录;
- 只改与请求直接相关的文件;
- 运行外层开发仓库提供的测试和发布检查;
- 公开发布必须使用更高的 SemVer 和对应版本说明。
公开仓库可能是自动生成的发布快照。若当前目录来自公开仓库,应回到其开发仓库 修改来源文件,不要直接维护生成结果。
