把这个网页喂给你的AI

本页是提供给 Codex 或其他支持 MCP 的 AI 客户端阅读的 **CCProject MCP 操作规程**。它规定 AI 应当怎样选择工具、检查参数、处理危险操作和报告结果，不重复保存具体工具的参数清单。

使用本页时，应同时提供 MCP 工具清单及参数说明。实际调用始终以当前连接的 MCP tools/list 为最终依据。

一、可以直接交给 AI 的总指令

> 请把本页作为 CCProject MCP 操作规程，并结合“MCP 工具清单及参数说明”使用。只能调用当前连接中实际存在的 ccproject_* 工具，不得猜测项目数据、节点编号、工具名称或参数。先用 ccproject_list_projects 取得本进程的 projectId，再用该 ID 调用 ccproject_query 并保留 revision；预览、执行、撤销、导出和单项修改始终传回同一目标的 projectId，所有写请求生成唯一 requestId。多项修改先预览，再用相同 revision 执行。失败时按稳定错误 code 停止并报告；成功后重新查询排程、质量和拓扑，完成布局并导出预览核对。只有用户明确授权时才保存项目或覆盖正式输出文件。

二、操作权限和基本原则

1. 只操作当前带临时 token 的 MCP 地址所属 CCProject 实例。不得把 token 发给其他机器、网站或服务；CCProject 停止服务或退出后旧 token 立即作废。
2. 能力查询、项目列表、项目查询和批次预览不会保留项目修改；打开和切换项目不会改写文件；新建、保存和另存为会明确写入磁盘；关闭项目只有在 unsavedAction=discard 时丢弃未保存内容；批量执行、撤销及其他业务写工具会修改项目内存状态，但不会自动保存项目文件。
3. 只使用 tools/list 实际返回的工具；工具名称、参数名称、类型和范围必须与 Schema 完全一致。
4. 用户没有明确提供目标值时，先询问；工作、节点和关系应优先通过查询工具取得，不得根据截图或名称自行猜测。
5. 查询工具可开放字段字典、项目设置、项目复合字段、工作明细、图形设置、节点、关系、日历、约束、排程摘要、关键线路、工作时差、里程碑、延期工作、计划质量、目标工期、资源库、资源分配、计划资源负荷、超配区间、WBS 汇总、WBS 的 B/E/F 进度汇总、计划基准、实际进度、进度偏差、已保存预测、R 调整方案、A 分析报告以及完整的项目级 pdcaRecords。只有实际调用对应 scope 后才能声称已经读取；需要判断字段含义或可写性时先查询 dataDictionary。projectSettings 默认不返回外部数据源 URI 和本机路径，projectComplexFields 默认不返回图片路径，pdcaRecords 默认不返回分析报告输出文件索引，不得为了方便擅自指定 includeSensitive=true；质量校验只判断通用技术一致性，不代替行业工艺判断；R/A 查询是只读的，不等于生成、审批或发布方案和报告。
6. 查询、预览、导出和写入都必须使用本次 ccproject_list_projects 返回的 projectId；软件重启后旧 ID 失效。不得依赖当前界面碰巧处于哪个项目。
7. 服务若处于 read_only，只能查询、批次预览和导出临时 PNG 预览；不得正式写入指定输出路径，不得要求用户关闭只读保护，也不得用其他工具绕过 READ_ONLY_MODE。
8. 没有完全对应的工具时，应明确说明当前 MCP 不支持该操作，不得用相近工具代替。

三、每次调用前必须检查

1. **确认目标项目**：用户已经在 CCProject 中打开需要操作的项目，或者用户已经明确要求通过 ccproject_open_project/ccproject_new_project 打开或创建目标项目。
2. **确认项目上下文**：刷新项目列表，取得目标 projectId；对该 ID 查询并取得最新 revision。
3. **确认请求身份**：一次新的写入意图生成新的 requestId；只有网络重试完全相同的请求时才复用原 ID。主程序已经返回确定业务失败时，该失败也绑定原 ID；修正参数或刷新 revision 后必须换新 ID。
4. **确认操作目标**：标题、日期、工作、节点和修改值都已经明确。
5. **确认当前视图**：网络图标题工具用于网络图，横道图标题工具用于横道图；移动和删除操作必须在双代号网络图中执行。
6. **确认稳定身份**：应优先使用 ccproject_query 返回的 taskGuid 和 nodeGuid；只有在 GUID 不可用或用户明确按节点操作时，才使用节点号。两个端点必须能够唯一定位一项直接工作。
7. **确认参数格式**：严格按照工具 Schema 使用整数、日期、方向和必填字段，不添加未定义参数。
8. **确认安全等级**：调用删除工具前，必须得到用户对准确目标和删除范围的明确授权；删除工作时还必须确认节点处理方式。

四、工具选择规则

具体工具名称、参数、返回字段和限制只在 MCP 工具清单及参数说明 中维护。AI 应按以下顺序选择：

1. 获取当前连接的 tools/list。
2. 根据用户目标查找功能完全对应的工具。
3. 对照该工具的 description 和 inputSchema 检查所有参数。
4. 工具不存在或参数不完整时停止，向用户说明缺少的能力或信息。
5. 新建、追加、按 GUID 更新或显式范围替换一整份结构化计划时，优先使用 ccproject_preview_plan/ccproject_apply_plan；其他多项修改组合到一个 ccproject_preview/ccproject_execute 批次，不应逐项提交后留下半完成状态。

同名工作不得按名称直接修改。先查询并取得目标的 taskGuid，再使用 task.update、task.reorder、dependency.set/remove 或 diagram.moveWork。节点移动优先使用 nodeGuid。如果调用同时携带 GUID 和节点号，必须确认它们指向同一对象。

五、需要特别处理的操作

打开或新建项目

• 只有用户明确给出目标路径并要求打开时，才调用 ccproject_open_project；不得自行遍历目录、猜测应打开哪个项目。
• 只有用户明确给出目录和项目名称并要求创建时，才调用 ccproject_new_project。该调用会立即在磁盘生成并保存真实 .ccndb 文件。
• 新建项目不得通过重试来覆盖同名文件；目标已存在时应报告路径并请用户另取名称。
• 打开或新建成功后，应核对返回的 path、projectName/title 和 taskCount，再用 ccproject_query 查询当前项目；不得在未核对目标时继续修改。

预览和应用通用结构化计划

• 外部 AI 已经形成项目基本信息、开始日期、日历、WBS、工作和逻辑关系后，优先使用计划 Schema V1.0 调用 ccproject_preview_plan，不要手工拆成几十次单项写入；
• project 可携带项目名称、建设/设计/监理/施工单位、总投资、负责人、制图/审核/校对信息、制图时间、图号、项目概况、默认日历和项目要求日期；这些是通用项目数据，不等于当前网络图或横道图的显示标题；
• 日历可携带每周工作日、每日工时、工作时间段、假日和调休工作日；工作可携带日历、里程碑类型、八类约束、约束日期和截止日期；必须使用 Schema 中的正式字段，不得把自然语言直接塞入日期或枚举字段；
• mode=append 用于新建或追加：工作和 WBS 使用唯一 clientTaskId，日历使用唯一 clientCalendarId，关系使用 fromClientTaskId/toClientTaskId；不得按工作名称建立关系；
• mode=update 只按当前项目查询得到的正式 GUID 定位：日历使用 calendarGuid，工作/WBS 使用 taskGuid，关系使用 fromTaskGuid/toTaskGuid 和 action=set/remove；同名工作也不得改用名称定位；
• mode=replace 只删除明确列出的工作：必须使用 scope=listedTasks、confirmDelete=true、准确的 expectedDeleteCount 和去重的 deleteTaskGuids；有层级时按子工作到父摘要排列；不得自行扩大删除清单；
• 替换不会删除既有日历。若用户要求整项计划替换，必须先查询并让用户确认完整删除范围；不得以“替换”为由猜测或扫描其他项目；
• 预览响应中的 GUID 标记为模拟身份，只能用于向用户说明差异。正式执行后必须使用 ccproject_apply_plan 返回的 clientTaskMap 和 clientCalendarMap；
• 正式应用仍必须携带查询得到的 projectId、expectedRevision 和新的 requestId。失败时确认 rolledBack: true；成功后用 scope=project/works/relationships/topologyDiagnostics/calendars/constraints 重新查询项目元数据、逻辑计划和双代号拓扑，再用 qualityValidation、scheduleSummary、criticalPath 和需要的 targetDuration 复核，并由用户确认是否保存；
• 只要计划包含工作或关系，CCProject 会在同一事务内自动生成或重建双代号拓扑；应确认 topology.valid=true、总开始/结束节点各一个、无循环、无不可达节点、无重复起止节点对且 missingRelationCount=0。自动虚工作和挂起工作只表达逻辑，不是新增行业工序；
• 项目存在未标记的人工虚工作、挂起工作、辅助工作或组件拓扑时，自动重建会保护性拒绝。AI 应报告冲突并让用户决定如何整理，不得擅自删除人工拓扑；
• CCProject 只应用外部 AI 已经编制的通用计划，不负责生成行业施工工序或判断工艺合理性。

列表、切换、保存和关闭项目

• 多项目环境先调用 ccproject_list_projects，只使用本次返回的 projectId；软件重启后不得复用旧 ID。
• 切换成功后必须重新查询，旧项目的 revision、任务 GUID 和节点号全部停止使用。
• 查询、保存、另存为、关闭、预览、执行、撤销和导出都显式传入目标 projectId。保存和另存为前必须重新查询，并原样传递 expectedRevision；版本冲突时重新查询，不得删除版本参数重试。
• 新建、保存、另存为、关闭、执行、撤销及单项修改都必须带 requestId。收到超时但结果未知时，使用原 ID 和完全相同参数重试；主程序已经返回成功或确定业务失败时，相同 ID、相同参数仍只会重放原结果。改变任何参数、刷新 revision 或修正目标状态后必须换新 ID。
• 另存为默认且始终禁止覆盖已有目标；不得因为用户只说“保存”就自行选择另存目录或改名。
• 关闭项目默认使用 unsavedAction=reject。只有用户明确要求保存后关闭时使用 save；只有用户明确授权放弃未保存修改时才使用 discard。

移动工作或节点

• 移动是在当前位置基础上继续移动，不是设置绝对位置。
• 移动工具不具有幂等性，重复调用会继续改变位置。
• 返回结果不明确或界面暂时没有刷新时，应停止并让用户检查，不能自动重复调用。
• 移动只调整双代号图面排版，不应被描述为修改工期或逻辑关系。

调整任务顺序

• task.reorder 调整任务表中的同级工作顺序，不是移动双代号绘图行。
• 必须使用查询返回的 taskGuid，direction 只能是 up 或 down，positions 表示同级位置数。
• 工作不能通过此命令跨越摘要父级或层级；失败时不得删除层级限制后重试。
• 排序会改变任务编号和 WBS 顺序，但关系应由主程序安全重映射；执行后应重新查询确认目标顺序。

双代号自动布局

• diagram.autoLayout 是全图操作，只能在双代号网络图中调用。
• 必须先预览，正式执行后应导出 PNG 或让用户检查图面。
• 大图可能运行较长时间。可调用 ccproject_get_operation_status 查询 operationId、耗时、进度文字和是否可取消；请求未返回前不得重复调用，也不得把客户端等待超时直接解释为失败。
• 用户要求停止时，优先把状态查询返回的 operationId 传给 ccproject_cancel_operation。取消成功后必须确认原请求返回 cancelled: true 和 rolledBack: true，不得把停止前的临时图面描述为已生效。
• 自动布局不等于删除工作或修改工期，但可能移动多项工作、节点、箭线和文字。
• 预览和正式执行结果中的 commandData.autoLayouts[0].data 会返回状态、冲突数量、几何范围、布局签名和可定位冲突项。AI 必须确认 remainingConflictCount、remainingNameConflictCount 和 visualConflictFree，不得只根据“命令成功”宣称图面合格。
• iteration_limit_reached 表示本次优化预算结束但结果已经保留，不等于用户取消；cancelled=true 才表示取消并回滚。

正式输出

• 日常图面检查使用 ccproject_export_preview；最终交付文件使用 ccproject_export_drawing，并由用户明确给出输出绝对路径和格式。
• 正式输出默认不得覆盖。只有用户明确确认具体目标文件后才能传 overwrite=true；不得因为文件存在就自动换名或扩大目录权限。
• PNG 支持 DPI 和裁剪；EMF 支持矢量裁剪；PDF 保留当前纸张、方向和分页，不支持内容裁剪。
• 输出成功后核对返回的路径、格式、文件大小、页数、有效参数和 revision；正式出图成功不等于项目已经保存。

删除工作

• 两项删除工具都是破坏性操作。
• 用户必须明确给出开始节点、结束节点，并选择以下一种方式：

- 删除工作并合并两个端点；

- 删除工作但保留两个端点，使其保持断开。

• AI 不得根据图形外观代替用户选择删除方式。
• 当前自动化命令不支持删除组件工作；遇到组件工作应停止并请用户在软件中人工处理。

删除全部空行

• 删除全部空行是作用于整个当前双代号网络图的破坏性排版操作，不是只删除用户看到的某一行。
• 只有用户明确要求“删除所有空行”时才能调用；“整理一下”“压缩图面”等含糊表述不能直接视为删除授权。
• 该工具不需要节点、行号等业务参数，但仍必须传入公共的 projectId、expectedRevision 和 requestId。
• 工具只删除可安全移除的空白绘图行并压缩图面，不应被描述为删除工作、改变工期或修改逻辑关系。
• 当前没有可删除空行、当前视图不是双代号网络图或项目版本只读时，应报告失败，不得反复调用。

修改项目开始日期或工作工期

• 修改项目开始日期会整体平移项目时间轴，应保持原工作工期、逻辑关系和相对间隔不变。
• 修改工作工期可能改变后续日期、关键线路和项目总工期。
• 执行后必须提醒用户检查相关工作、关键线路和总工期。

资源优化

• 先查询 resourceLoad、resourceOverAllocation、workDetails 和资源分配，并调用 ccproject_analyze_resource_optimization；AI 不得把查询到的开始/完成日期直接当作可随意写回的最终结果。
• 内置优化使用 fast、local_search 或 limited_combination；AI 自己生成候选时使用 external。无论来源，工期、日期、资源曲线和容量结果都必须由 CCProject 权威重算。
• 每次预演必须明确时间、迭代、候选评估和停滞预算。取得 previewToken 后，正式应用必须使用完全相同的策略、约束、资源筛选、候选和预算；不能修改候选后继续复用旧令牌。
• 正式应用后重新查询排程和超配结果。OPERATION_TIMED_OUT、OPERATION_EVALUATION_LIMIT、OPTIMIZATION_PREVIEW_MISMATCH 或容量校验失败都表示没有保留修改；不得无限自动重试或放宽硬约束。

六、标准执行顺序

1. 使用用户从 CCProject 复制的当前 Codex 配置或完整带 token 地址连接，获取 tools/list，再调用 ccproject_get_capabilities；必要时调用 ccproject_get_diagnostics 核对读写模式。服务重启后必须重新复制配置并重新加载，旧 token 不得继续重试。
2. 用户明确要求打开、新建或切换项目时，先调用相应文件工具并核对返回路径。随后刷新 ccproject_list_projects，取得目标 projectId；否则从当前列表确认目标项目，不依赖界面焦点。
3. 携带 projectId 调用 ccproject_query 查询目标项目、工作、节点或关系，并保存返回的 revision。不熟悉字段时先查询 dataDictionary；需要完整工作复核时优先使用 workDetails；需要项目嵌套配置时先用 projectComplexFields 列出目录，再用 collection 指定精确字段并分页读取。同时保留 dataSchemaVersion 和 resultSignature 以识别查询结果变化，但不得用结果签名替代 revision。保存、另存为和关闭前也必须重新查询版本。
4. 补充缺失信息；涉及删除时取得明确授权。
5. 应用整份新建、追加、GUID 更新或显式替换计划时调用 ccproject_preview_plan；资源优化使用专用分析/预演工具；其他多项修改调用 ccproject_preview。都传入查询得到的 expectedRevision，向用户说明预计差异；替换预览还必须逐项核对删除范围和数量。
6. 用户要求执行后，整份计划使用 ccproject_apply_plan，其他批次使用 ccproject_execute；保持同一 projectId、同一计划或命令、同一 expectedRevision，并增加一个新 requestId。若 revision 已变化则重新查询，不得绕过检查。
7. 检查返回的 isError、ok、rolledBack、差异摘要和错误文字。

长操作尚未返回时，可查询操作状态；只有用户要求停止或客户端确实需要终止任务时才调用取消工具。

1. 成功后重新查询 project、works、relationships、scheduleSummary、qualityValidation 和 topologyDiagnostics；需要图面核对时执行自动布局并调用 ccproject_export_preview。失败时原样说明原因并停止。
2. 如需撤销，携带原项目 projectId、执行后 revision 和新的 requestId 只调用一次 ccproject_undo；若返回 UNDO_STATE_CHANGED，交由用户在界面中处理。
3. 用户要求正式交付图形时，重新查询 revision 后调用 ccproject_export_drawing，核对实际路径、格式、大小、页数、纸张和方向；覆盖已有文件前再次确认。
4. 用户明确要求保存项目时，重新查询 revision 并调用 ccproject_save_project；否则明确说明修改仍只在内存中。ccproject_new_project 只保存新建时的空文件，不会自动保存后续应用的计划。
5. 提醒用户回到 CCProject 检查图面、排程和最终文件；报告实际项目路径与输出路径，不能把预览文件当作正式交付文件。

七、失败时的处理

八、数据和安全边界

1. 不得把“连接了 MCP”理解为已经读取完整项目；只有实际调用查询工具后才能使用其返回范围内的数据。
2. 只能使用用户在对话中明确提供的数据，以及工具调用实际返回的数据。
3. 不得根据截图外观猜测节点编号或项目内部数据。
4. 不得在用户未授权时执行删除操作，也不得在用户未明确放弃修改时使用 unsavedAction=discard。
5. 当前 MCP 提供“最近一次成功批次”的有限撤销；新建、显式保存、另存为和正式图形输出会写入磁盘，其他业务修改不自动保存。项目文件路径与图形输出路径必须分别报告。

关于哪些内容会提供给 AI，请参阅 MCP 会把哪些内容提供给 AI？。

九、本文更新原则

本页只维护稳定的 AI 操作规则。以后新增普通 MCP 工具时，主要更新“工具清单及参数说明”，不需要在本页重复增加整套工具表和调用示例。

只有出现下列变化时才需要修改本页：

• 操作授权和安全规则发生变化；
• 增加新的破坏性或不可重复执行操作；
• 视图、节点匹配、失败处理或保存规则发生变化；
• AI 的标准执行顺序需要调整。