夜雨聆风一、前置准备
依赖项 | 版本要求 | 说明 | 必须 |
Node.js | ≥ 18.x | Viewer 服务器运行时 | 是 |
Git | ≥ 2.30 | 用于代码 diff、worktree 管理 | 是 |
Claude Code (CLI) | 最新版 | 流水线的 AI 执行引擎 | 是 |
Java 后端项目 | — | 你的团队自己的源码库（Maven 项目） | 是 |
MCP | 治水MCP SFdoc confluence-mcp | 文档末尾有配置，添加到.claude.json | 可选 |
MCP-个人专属 | dingtalk-docs | 钉钉文档mcp，从钉钉文档读取需求文档 | 可选 |
二、安装下载
仓库地址：https://inner-source.sf-express.com/01387722/isco-ai
方式一：直接clone项目代码到本地
git clone https://inner-source.sf-express.com/01387722/isco-ai.git
方式二：加入本地claude markplace管理
（1）一次性手动:输入工号密码 （bash执行）
git clone https://inner-source.sf-express.com/01387722/isco-ai.git
（2）加入marketplace到本地claude code （claude中执行）
/plugin marketplace add https://inner-source.sf-express.com/01387722/isco-ai.git
（3）安装pipeline插件 （claude中执行）
/plugin install isco-pipeline@isco-marketplace-pipeline
三、快速开始
3.1 初始化
如果通过方式一clone项目，需要进入项目根目录执行初始化
windows执行init.bat
mac执行init.sh
3.2 修改配置文件 pipeline-config.json
这是唯一需要编辑的文件， 其他 Agent/Skill 都会自动读取此配置中的路径值。文档末尾有完整示例
（1）打开配置文件
plugins/isco-pipeline/pipeline-config.json
（2）修改路径配置
{"_comment": "百川 Pipeline 路径配置文件。新团队使用时只需修改此文件中的路径值。","_usage": {"_description": "Skills 和 Agents 执行前会读取此配置获取所有路径。Viewer (server.js) 启动时自动读取此配置。","_howToRead": "通过 paths.sourceRepos 获取所有源码库及其路径，key 为模块名，value 为绝对路径。不同团队可按实际情况增减模块。","_example": "你的团队只有 3 个源码库？只需在 sourceRepos 中保留 3 个 key。有 10 个？添加 10 个即可。Skills/Agents 会动态读取所有 key。"},"paths": {"_comment_sourceRepos": "源码库路径。按实际目录结构自由增减。key=模块名(任意), value=绝对路径。你的团队可自由调整。","sourceRepos": {"service1": "xxx/your/service1","service2": "xxx/your/service2"},"_comment_docRoot": "流水线各阶段产出文档的根目录","docRoot": "文档目录，你本地目录的绝对路径","_comment_worktreeRoot": "Git worktree 工作目录根路径","worktreeRoot": "git分支目录，","_comment_gitBash": "Git Bash 可执行文件路径（Windows 下 Git 安装目录）","gitBash": "E:/Git/bin/bash.exe"},"pipeline": {"_comment": "流水线阶段配置。新团队按需修改 stages 数组即可定制流水线。","name": "xxx Pipeline","description": "从需求分析到上线配置的 10 阶段流程","stages": [{"id": "S1","name": "用户需求分析","summary": "分析用户需求，聚焦后端范围，生成需求规格文档","skill": "可以根据团队情况更新skills","outputFile": "s1-requirement-analysis.md","kbQuery": true},{"id": "S2","name": "用户需求拆解","summary": "将需求拆解为可执行的开发任务列表","skill": "requirement-split","outputFile": "s2-requirement-split.md","kbQuery": true},{"id": "S3","name": "源码分析","summary": "按源码库并行分析相关代码、调用链和SQL逻辑","agent": "code-explorer","outputFile": "s3-source-analysis-{module}.md","kbQuery": true,"parallel": true},{"id": "S4","name": "系统需求创建","summary": "在治水平台创建系统需求","mcp": "zhishui-mcp.createSystemNeed","outputFile": "s4-system-requirement.md","kbQuery": false,"requiresUserInput": "用户需求ID"},{"id": "S5","name": "系统需求评审","summary": "对系统需求进行结构化评审","orchestrator": true,"outputFile": "s5-review-report.md","kbQuery": false},{"id": "S6","name": "研发计划","summary": "编写详细的开发执行计划，每步标注源码库","skill": "可以根据团队情况更新skills名称","outputFile": "s6-execution-plan.md","kbQuery": true},{"id": "S7","name": "编码执行","summary": "按源码库并行执行编码任务","agent": "coding-executor","outputFile": "s7-code-changes.md","kbQuery": true,"parallel": true,"loopGroup": "dev-cycle"},{"id": "S8","name": "Code风险评估","summary": "代码评审，阻塞问题需回S7修复","skill": "可以根据团队情况更新skills名称","outputFile": "s8-code-review.md","kbQuery": true,"loopGroup": "dev-cycle"},{"id": "S9","name": "测试验证","summary": "执行测试，失败需回S7修复","skill": "可以根据团队情况更新skills名称","outputFile": "s9-test-report.md","kbQuery": false,"loopGroup": "dev-cycle"},{"id": "S10","name": "上线配置整理","summary": "扫描上线配置变更，生成配置清单","skill": "release-config","outputFile": "s10-release-config.md","kbQuery": false,"autoArchive": true}],"loopGroups": {"dev-cycle": {"stages": ["S7", "S8", "S9"],"description": "S8评审阻塞或S9测试失败 → 回S7修复；S8无阻塞且S9通过 → 退出循环"}},"gates": [{"id": "branch-confirm","after": "S5","before": "S6","name": "分支确认","agent": "branch-manager","description": "创建 git worktree，为 S6-S9 提供隔离开发环境"}]}}
各字段说明：
配置项 | 说明 | 示例 |
| 源码库路径映射。key = 模块名（任意命名），value = 源码库绝对路径。根据你的团队实际情况自由增减。3 个模块就写 3 个，10 个就写 10 个。 |
|
| 文档输出根目录。流水线各阶段产出的 Markdown 文件统一保存到此目录。 |
|
| Git worktree 工作目录根路径。当需要在独立 worktree 中操作分支代码时使用。 |
|
| Git Bash 可执行文件路径（Windows）。用于执行 git 命令。 |
|
关键要点：
sourceRepos 的 key 名自由定义：
module-a、order-service、user-center都可以，Agent 和 Skill 会动态读取所有 key，不做限制。路径使用正斜杠
/：Windows 路径也建议用/（如E:/your-team/repo），不影响 Git 操作。docRoot 目录需提前创建：确保目录存在且有写入权限。
3.3 启动viewer管理后台面板
（1）打开配置文件
plugins/isco-pipeline/viewer/pipeline.json
（2）修改路径配置 docRoot、workDir
[{"id": "isco-pipeline","name": "百川 AI Pipeline","description": "百川系统研发流水线：从需求分析到上线配置的 10 阶段流程","icon": "rocket","skillName": "isco-pipeline","docRoot": "D:\\Doc\\claude-doc","sessionPrefix": "isco","workDir": "D:\\isco-ai","_stagesNote": "stages 由 pipeline-config.json 中的 pipeline.stages 定义，server.js 启动时动态读取","metadataFields": [{ "key": "commonVersion", "label": "common 版本" },{ "key": "involvedRepos", "label": "涉及库", "join": ", " },{ "key": "branchInfo", "label": "分支", "format": "object-values", "join": " | " },{ "key": "userNeedId", "label": "用户需求ID" },{ "key": "systemNeedId", "label": "系统需求ID" }]}]
运行：
cd plugins/isco-pipeline/viewer
node server.js
或双击 start.bat 脚本，如果端口占用可执行restart.bat
文件目录：plugins/isco-pipeline/viewer
启动后访问：http://localhost:12345
默认端口为 12345，可通过环境变量 PORT 修改。
3.4 创建需求流水线
（1）方式一：本地打开claude窗口，调用/isco-pipeline
根据提示输入需求名称、需求内容/需求文档链接。也可以指定当前需求从第几个环节开始，同时也可以看到历史session
（2）方式二：viewer面板创建需求，建议session名称为英文，再打开claude控制台执行/isco-pipeline
3.5. 验证配置
（2）检查 Viewer 首页
打开 http://localhost:12345，确认：
页面正常加载
流水线列表可见（来自
pipelines.json的定义）无路径相关的报错
（1） 测试流水线执行
在 Viewer 首页选择一个流水线，点击启动：
等待 ChatSession 创建完成
流水线应自动开始执行 S1 阶段
产物文件应出现在
docRoot指定目录下
3.6. 可选：自定义流水线阶段
编辑 viewer/pipelines.json，根据需要调整流水线阶段定义。默认流水线结构：
阶段 | 名称 | 说明 |
S1 | 需求分析 | 分析原始需求并生成结构化需求文档 |
S2 | 需求拆分 | 将原始需求拆分为独立用户需求 |
S3 | 源码分析 | 分析相关源码，定位改动点 |
S4 | 系统需求创建 | 在治水平台中创建系统需求 |
S5 | 方案设计 | 设计改动方案 |
S6 | 方案评审 | 评审改动方案 |
S7 | 编码执行 | 执行代码修改 |
S8 | 代码风险评估 | 评估改动风险 |
S9 | 测试用例生成 | 生成测试用例 |
S10 | 上线配置整理 | 扫描配置变更并生成清单 |
四. 常见问题
Q1: 启动后 Viewer 页面空白？
A: 检查 pipeline-config.json 是否格式正确（逗号、引号），用 JSON 校验工具验证。
Q2: 流水线执行时提示路径找不到？
A: 确认 pipeline-config.json 中的路径均真实存在：
sourceRepos下每个路径对应一个实际的 Git 仓库目录docRoot目录已创建且有写入权限gitBash指向正确的 Git Bash 可执行文件
Q3: 我的团队源码库数量不同怎么配？
A: 直接在 sourceRepos 中增删 key 即可。例如只有 3 个源码库：
"sourceRepos": { "frontend": "E:/team/frontend", "backend": "E:/team/backend", "common": "E:/team/common-lib"}Q4: 不想用 worktree 可以吗？
A: 可以。如果不需要 worktree 功能，worktreeRoot 配一个任意路径即可，不影响主流程。
Q5: macOS / Linux 怎么配？
A: gitBash 字段在 macOS/Linux 上不需要（系统自带 git），可以保留一个占位值。路径使用 Unix 风格即可（如 /Users/xxx）。
五、附录：配置文件完整示例
{"_comment": "百川 Pipeline 路径配置文件。新团队使用时只需修改此文件中的路径值。","_usage": {"_description": "Skills 和 Agents 执行前会读取此配置获取所有路径。Viewer (server.js) 启动时自动读取此配置。","_howToRead": "通过 paths.sourceRepos 获取所有源码库及其路径，key 为模块名，value 为绝对路径。不同团队可按实际情况增减模块。","_example": "你的团队只有 3 个源码库？只需在 sourceRepos 中保留 3 个 key。有 10 个？添加 10 个即可。Skills/Agents 会动态读取所有 key。"},"paths": {"_comment_sourceRepos": "源码库路径。按实际目录结构自由增减。key=模块名(任意), value=绝对路径。示例只列出 百川 团队的 6 个模块，你的团队可自由调整。","sourceRepos": {"baseinfo": "D:/user/01452209/program/isco-ai-test/ibu-isco-core-baseinfo","inbound": "D:/user/01452209/program/isco-ai-test/ibu-isco-core-inbound","outbound": "D:/user/01452209/program/isco-ai-test/ibu-isco-core-outbound","inventory": "D:/user/01452209/program/isco-ai-test/ibu-isco-core-inventory","service": "D:/user/01452209/program/isco-ai-test/ibu-isco-core-service","common": "D:/user/01452209/program/isco-ai-test/ibu-isco-core-common"},"_comment_docRoot": "流水线各阶段产出文档的根目录","docRoot": "D:/Doc/claude-doc","_comment_worktreeRoot": "Git worktree 工作目录根路径","worktreeRoot": "D:/isco-worktrees","_comment_gitBash": "Git Bash 可执行文件路径（Windows 下 Git 安装目录）","gitBash": "D:/user/01452209/soft/Git/bin/bash.exe"},"pipeline": {"_comment": "流水线阶段配置。新团队按需修改 stages 数组即可定制流水线。","name": "百川 AI Pipeline","description": "百川系统研发流水线：从需求分析到上线配置的 10 阶段流程","stages": [{"id": "S1","name": "用户需求分析","summary": "分析用户需求，聚焦后端范围，生成需求规格文档","skill": "superpowers:brainstorming","outputFile": "s1-requirement-analysis.md","kbQuery": true},{"id": "S2","name": "用户需求拆解","summary": "将需求拆解为可执行的开发任务列表","skill": "requirement-split","outputFile": "s2-requirement-split.md","kbQuery": true},{"id": "S3","name": "源码分析","summary": "按源码库并行分析相关代码、调用链和SQL逻辑","agent": "code-explorer","outputFile": "s3-source-analysis-{module}.md","kbQuery": true,"parallel": true},{"id": "S4","name": "系统需求创建","summary": "在治水平台创建系统需求","mcp": "zhishui-mcp.createSystemNeed","outputFile": "s4-system-requirement.md","kbQuery": false,"requiresUserInput": "用户需求ID"},{"id": "S5","name": "系统需求评审","summary": "对系统需求进行结构化评审","orchestrator": true,"outputFile": "s5-review-report.md","kbQuery": false},{"id": "S6","name": "研发计划","summary": "编写详细的开发执行计划，每步标注源码库","skill": "superpowers:writing-plans","outputFile": "s6-execution-plan.md","kbQuery": true},{"id": "S7","name": "编码执行","summary": "按源码库并行执行编码任务","agent": "coding-executor","outputFile": "s7-code-changes.md","kbQuery": true,"parallel": true,"loopGroup": "dev-cycle"},{"id": "S8","name": "Code风险评估","summary": "代码评审，阻塞问题需回S7修复","skill": "superpowers:requesting-code-review","outputFile": "s8-code-review.md","kbQuery": true,"loopGroup": "dev-cycle"},{"id": "S9","name": "测试验证","summary": "执行测试，失败需回S7修复","skill": "superpowers:test-driven-development","outputFile": "s9-test-report.md","kbQuery": false,"loopGroup": "dev-cycle"},{"id": "S10","name": "上线配置整理","summary": "扫描上线配置变更，生成配置清单","skill": "release-config","outputFile": "s10-release-config.md","kbQuery": false,"autoArchive": true}],"loopGroups": {"dev-cycle": {"stages": ["S7", "S8", "S9"],"description": "S8评审阻塞或S9测试失败 → 回S7修复；S8无阻塞且S9通过 → 退出循环"}},"gates": [{"id": "branch-confirm","after": "S5","before": "S6","name": "分支确认","agent": "branch-manager","description": "创建 git worktree，为 S6-S9 提供隔离开发环境"}]}}"confluence-mcp": {"args": ["/c","npx","-y","@sf/confluence-mcp"],"command": "cmd.exe","env": {"CONFLUENCE_URL": "https://confluence.sf-express.com","NPM_CONFIG_REGISTRY": "https://artifactory.sf-express.com/artifactory/api/npm/npm/"}},"sfdoc": {"args": ["/c","npx","-y","@sf/sfdoc-mcp"],"command": "cmd.exe","env": {"NPM_CONFIG_REGISTRY": "https://artifactory.sf-express.com/artifactory/api/npm/npm/"},"type": "stdio"},"zhishui-mcp": {"headers": {"platType": "sfcloud","sf-cicd-mcp-token": "3a4451b6434f4992a50cb17e4ac3116f"},"type": "http","url": "https://sdeis-ai.sf-express.com/plugin-api/mcp"}
