ns-langgraph-agents

LangGraph Agents

生产级 LangGraph.js（Node 24+、TypeScript 严格模式、@langchain/langgraph）。

负责运行时规范——放置、提示词/能力注入、图规范同步。通过 ns-coder 或 ns-autonomous 提交差异。框架选择：ns-agent-architecture。

适用范围

上下文	规范强度
Greenfield agent-api（新的 LangGraph 运行时）	MUST 遵循构建工作流关卡——dev-chat、预算、先规范化再截断、单独的技能上限。拓扑：对于大多数 MCP/工具密集型场景，建议使用 plan_execute——在 graph-spec.md 中锁定；这不是硬性规则
Brownfield 现有 Agent	RECOMMENDED 迁移并采用相同的控制措施；孤立恢复不会因缺少拓扑而触发 Critical 失败
有意进行 MCP 重新设计	在同一交付中同步 graph-spec.md 和相关引用——对涉及的拓扑/预算/证据章节，按 Greenfield MUST 处理

在有意更改拓扑之前，Brownfield 中开放的 ReAct 仍然有效。Greenfield MUST 仅适用于新的 agent-api + 有意进行 MCP 重新设计。

路由（先阅读）

信号	操作
概念设计尚未确定（Agent vs RAG vs 微调）	停止 → ns-agent-adaptation
未锁定框架 / 请求使用 CrewAI	停止 → ns-agent-architecture
孤立 / 结构丢失 / 布局不清楚	在实现功能之前运行孤立检查清单（references/orphan-recovery-checklist.md）
GitLab ISSUE_URL 或 SDD 版本范围	交由 harness ../../ns-harness/references/code-skill-routing.md 处理——不要纳入本技能
已准备好获批的放置/注入计划，可提交差异	交由 ns-coder 实施——Greenfield 引导复制除外（references/bootstrap-agent-runtime.md）

启动（必需）

参见 ../../ns-harness/references/session-boot.md——先在其中完成 Session boot（阻塞项），然后：

1. 涉及运行时操作时，确认 {agent_api_root} 和 graph-spec.md
2. 在确定路径前加载放置/注入参考资料（references/placement-and-domains.md、references/prompt-and-capability-injection.md）
3. 继续使用本技能

**成功：**放置 + 注入规范 + 项目规则。**失败：**臆造文件夹或外部框架。

适用场景

情况	操作
全新 agent-api（没有 {agent_api_root}/package.json）	构建工作流：先执行阶段 0，再执行阶段 1 引导 — references/bootstrap-agent-runtime.md
棕地项目 / 孤立的运行时	添加功能前，先执行孤立项目恢复（references/orphan-recovery-checklist.md）
新文件 / 文件夹位置不明确	位置决策模块 + references/placement-and-domains.md
系统提示词 / 技能注入 / 绑定	提示词/能力计划 + references/prompt-and-capability-injection.md
拓扑 / 状态 / 能力 / guard_fail_mode 变更	规范同步关卡 — 在同一交付中更新 graph-spec.md
MCP 服务端/工具较多	阅读 references/mcp-complex-access.md + references/capability-governance.md
Token 激增 / 轮次变慢	阅读 references/context-window-and-tokens.md
Agent 必须记住用户（偏好、术语、CRUD）	阅读 references/user-memory.md — 按用户存储、推断并告知、/memories 路由
不可信输入 / 注入 / 声称拥有权限	阅读 references/guardrail-and-adversarial.md — 范围分类器；脚手架默认开放 ≠ 原则
对成本敏感的高用量 / 模型层级 / 缓存	阅读 references/model-cascade-and-cache.md
提供方消息/推理方面的特性	阅读 references/message-content-blocks.md
HITL / 流式 UX	阅读 references/streaming-and-hitl.md
JSON 规划器 / 分析器选择工具	操作进度通道 — templates/contracts/planner-contract.md + references/streaming-and-hitl.md
提示词变更 / 重复跳转 / 循环 / 声称“已修复”	阅读 references/turn-flow-gates.md — 流程优先、终止、重复、证据关卡
合并前评估	阅读 references/evals-and-gates.md

核心原则

LangGraph = 控制流。MCP／本地工具 = 图中的能力。图状态保持精简（引用、摘要）。检查点保存完整状态；上下文窗口是大模型的视图——两者要分开。

系统提示词： 每次调用大模型时，组合 base_invariant（引擎）和 injected（产品角色）。绝不在图状态、检查点或持久化的 messages 中保存组合后的系统／角色文本。索引 0 处的摘要 SystemMessage ≠ 完整系统提示词——参见 references/prompt-and-capability-injection.md、references/message-content-blocks.md。

语言区域： 使用对话中观察到的 turnLocale（优先检测人类消息，结合意图槽位）；configurable.locale 仅为弱提示；在代码中使用 Intl 格式化器——不要使用固定的启动语言区域。参见 references/evidence-and-fidelity.md、templates/snippets/conversation-locale.ts.snippet。

操作员进度（JSON 规划器跳转）： 对于全新项目，使用 streaming_sse，并让规划器／分析器输出结构化的 executionPlan（该跳转不使用 bindTools）；必须在 AgentState 上持久化 userFacingIntent（或 analysis.userFacingIntent）和 executionPlan。userFacingIntent 的语言必须与当前用户消息（最后一条 HumanMessage）一致——除非该消息为英语，否则不得使用英语；也不得使用产品默认语言区域。机器意图 intent 保持为英语，以便审计。在下一跳的节点入口处从该字段发出 SSE thinking——不要在 response_streaming 中发出，也不要写入持久化的 messages。第 0 跳使用 conversation/presentation/ 中的通用文案（或语言区域文案），并且必须与操作员使用同一种语言。开放式 ReAct + ToolNode 仅使用 tool_started／tool_finished。详情：templates/contracts/planner-contract.md、references/streaming-and-hitl.md。

三种绑定到模型的能力类型：

类型	LLM 线缆名称	内部 ID
本地工具	{name}	local:{name}
MCP 工具	mcp__{server}__{tool}	mcp:{server}:{tool}
技能流程	use_skill__{id}	skill:{id}

线缆名称必须匹配 ^[a-zA-Z0-9_-]{1,128}$（使用 __ 分隔符；冒号仅用于内部 ID）。新线缆名称中包含冒号，在评审中属于严重问题。

变更前检查

添加新文件或更改注入／绑定前：完成以下三项。发布前不得编写代码。

1. 放置决策块

### Placement Decision Block

- Artifact: …
- Type: …
- Target path: …
- Layer: …
- Refs: placement-and-domains.md
- do_not_create_under: […]

完整矩阵：references/placement-and-domains.md。

2. 提示词／能力计划

### Prompt / Capability plan

- Compose: base_invariant + injected (rebuild per invoke; not in state/checkpointer/durable messages)
- Motor (`base_invariant`): [gather-no-Markdown / sole-writer / tool discipline / JSON planner userFacingIntent is SSE not Markdown / …]
- Product (`injected`): canonical path + persona/tone notes; mode-resolved: yes/no; modes: [...]; resolver: ...
- System layers touched: […]
- Canonical prompt path: …
- Session overlay: yes/no
- Bind list: […]
- Auto-inject skills: […] (exclusive of bind for same id)
- Truncate caps: tool vs skill body
- Bind parity: …
- Spec paths to sync: […]

完整原则：references/prompt-and-capability-injection.md。规划／模式解析：references/prompt-and-capability-injection-plan-execute.md。

3. 规范同步检查

更改节点、边、状态、能力、recursion_limit、线缆名称或 guard_fail_mode：在同一次交付中更新 graph-spec.md。过时的归档 ≠ SoT——将规范同步到预期运行时；不要强行让线上代码适配过时的归档。

参考索引

按需加载——不要试图记住整个文件。

参考资料	何时阅读
references/bootstrap-agent-runtime.md	从零开始复制 templates/agent-runtime/
references/orphan-recovery-checklist.md	项目结构不明确或 Agent“迷失”时
references/runtime-layout.md	搭建脚手架、重构、分层违规
references/placement-and-domains.md	文件放在哪里；领域、图与配置的区别
references/prompt-and-capability-injection.md	系统提示词层、绑定与注入、绑定一致性
references/prompt-and-capability-injection-plan-execute.md	提示词/能力计划；plan_execute 的收集与编排；按模式解析的 injected
references/message-content-blocks.md	不同提供商中的 AIMessage/HumanMessage/ToolMessage
references/context-window-and-tokens.md	裁剪、摘要、工具与技能正文上限、context_manager
references/mcp-complex-access.md	多服务器 MCP、发现、传输、生命周期
references/capability-governance.md	允许列表、分类、速率限制、工具预算
references/evidence-and-fidelity.md	基于状态的证据、保真度门控、从对话中观察到的区域设置
templates/snippets/conversation-locale.ts.snippet	resolveConversationLocale + Intl formatUserFacing
templates/snippets/tool-budget.ts.snippet	每轮工具/MCP 上限、基于参数指纹跳过重复调用
templates/snippets/prepare-llm-messages.ts.snippet	context_manager 助手
references/error-and-reliability.md	工具错误、熔断器、重试、补偿、并行过时、成本停止
references/model-cascade-and-cache.md	低成本优先级联、两个信号满足其一即升级、语义/提示词缓存；不是 LLM intent_classify 跳转
references/observability.md	Postgres 审计、保留期限 = 租户时钟、按租户+时段+单项决策查询、成本预留
references/architectures.md	ReAct、plan_execute（大多数 MCP 的建议起点）、Reflection 层级、其他拓扑；节点 ID ≠ 状态通道
references/guardrail-and-adversarial.md	范围/安全分类器；失效开放脚手架 ≠ graph-spec 锁定；不是 Gateway 路由
references/streaming-and-hitl.md	SSE 信封、操作员 thinking、interrupted、恢复 SSE、interrupt()、Command 恢复
references/turn-flow-gates.md	提示词/循环故障：流程优先、终止、重复、工具错误、DoD
templates/contracts/planner-contract.md	JSON 规划器跳转：executionPlan + userFacingIntent
references/user-memory.md	每用户长期记忆：类型、推断并告知的写入路径、每次调用时读取、/memories CRUD、LGPD
references/evals-and-gates.md	架构、工具选择、记忆评估；黄金集晋级
references/anti-patterns.md	标记完成前的审查门控——热路径
references/anti-patterns-extended.md	过时的提示词副本、状态/记忆、可靠性、图、MCP、LLM、运维、流程
模板：templates/agent-runtime/（全新项目目录树）、templates/graph-spec.md、templates/contracts/、templates/snippets/（存量项目补丁）。

会话输入

变量	必填
{agent_api_root}	默认值为 agent-api
{task}	要构建、修复或审查的内容

孤立项目恢复（优先处理存量项目）

运行时结构混乱或团队受阻时：

1. 阅读 references/orphan-recovery-checklist.md；为项目评分。
2. 差距报告：结构、文件放置、上下文窗口、注入/绑定一致性、MCP 治理、HTTP、规范同步。
3. 按顺序制定修复计划（若计划较大，每条消息处理一个阶段）。
4. 通过 ns-coder 实施。

在布局和治理基线通过之前，不得添加新的图节点或 MCP 服务。

构建工作流（全新项目或恢复后）

阶段 0 — 规范门禁

如果缺少 graph-spec.md，请根据 templates/graph-spec.md 创建。最低限度需包含以下章节：锁定的头部信息（framework、architecture、interaction_mode、guard_fail_mode）、领域归属、提示词组合、状态 schema、节点表、边、中断、记忆、能力绑定/注入表、recursion_limit、HTTP 路由。

如果用户尚未决定架构，先停止并调用 ns-agent-architecture。

阶段 1 — 骨架

如果缺少 {agent_api_root}/package.json，运行 scripts/bootstrap-agent-runtime.mjs（references/bootstrap-agent-runtime.md）。然后在 {agent_api_root} 中运行 npm install && npm test。

不要使用 templates/snippets/ 拼装目录树。不要复制其他产品。复制后：使 src/graph/ 与 graph-spec.md 保持一致；在后续阶段或通过 ns-coder 将领域代码放入 conversation/ + config/。

对于已有目录树的存量项目：根据 references/runtime-layout.md 对齐——仅将代码片段用于补丁。

阶段 2 — 状态与持久化

完成引导后，验证以下内容是否存在；不要重新搭建。仅补齐与 graph-spec.md 不一致的部分。

• 带有 messages reducer 的 AgentState（Annotation.Root 或 Zod + MessagesZodMeta）。
• 开发/生产环境使用 PostgresSaver；仅在 tests/setup.ts 中使用 MemorySaver。
• 长期记忆（当 graph-spec.md 将其设为锁定项时）：按用户划分（tenant_id + user_id），绝不能按 thread_id 划分——参见 references/user-memory.md。
• 每次 invoke/stream：通过 buildRunConfig 设置 configurable.thread_id。
• JSON 规划器/分析器（该步骤不使用 bindTools）：在 graph-spec.md 状态 schema 中声明 executionPlan + userFacingIntent（或将其嵌套在 analysis 中）——参见 templates/snippets/state.ts.snippet。

阶段 3 — LLM 与消息

• 在 src/llm/ 中配置 Provider（仅限基础设施，不包含领域提示词）。
• 每个模型角色使用一个环境变量（例如聊天、摘要、嵌入）——源代码中不得硬编码模型 ID。
• 更改嵌入模型会使向量索引失效 → 必须完整重新填充索引。
• 图/节点单元测试：默认层级使用伪造的 LLM。需要真实模型的提示词/护栏行为测试 → 实时层级（测试层级参见 ns-harness → docker-and-testing.md）。
• 结构化轮次优先使用 JSON 模式 + Zod 解析；避免在兼容 OpenAI 的本地服务器上使用 withStructuredOutput。
• 通过 contentBlocks / content_blocks 规范化 Provider 输出——参见 references/message-content-blocks.md。

阶段 4 — 上下文窗口（必需）

按照 references/context-window-and-tokens.md 实施：

• 每次调用 LLM 前运行 trimMessagesForLlm。
• 在 ToolMessage 进入状态前，先运行 normalizeMcpToolResult，再运行 truncateToolOutput。
• 为技能正文单独设置 CONTEXT_SKILL_BODY_MAX_CHARS（代码片段为 skillBodyMaxChars）。
• 已用 token 超过 CONTEXT_MAX_TOKENS（原始窗口）的 80% 时进行摘要。比例为常量：触发值 0.8、压缩至 0.5、摘要上限 0.1。不设置摘要倍数环境变量。
• 使用持久化压缩实现 summarizeOlderMessages（RemoveMessage + 重写），并在同一 Agent 节点返回。

绝不能将原始 state.messages 传给模型。

阶段 5 — 能力

1. src/tools/ 中的本地 StructuredTool。
2. MCP：受治理的客户端 — 发现 → 本地允许列表 → 线上名称 → 单例客户端生命周期（references/mcp-complex-access.md）。
3. Skills：自动发现 skills/*.md → use_skill__{id} 或自动注入（每个 id 只能二选一）。

在 bindTools 之前应用 references/capability-governance.md 和 references/prompt-and-capability-injection.md。强制执行 绑定一致性。绑定 MCP 或外部工具时，使用 templates/snippets/tool-budget.ts.snippet 配置每轮工具/MCP 预算。

阶段 6 — HTTP 和交互模式

模式	要求
sync_json	POST /threads、POST /threads/:id/message
streaming_sse	遵循 references/streaming-and-hitl.md 中的 SSE 信封；编排器回复 必须使用 model.stream() + 累积式 response_streaming tick（不能使用 invoke-dump）；SSE flush 立即执行；dev-chat 每个 tick 使用 flushSync；greenfield 必须提供带样式的 React GET /dev-chat（DEV_CHAT_ENABLED，仅本地）+ GET /dev-chat/app.js；JSON 规划器跳转 必须发出供操作人员查看的 thinking；提供 Docker 制品（Dockerfile、仅包含 Agent 的 compose）
HITL	interrupt() + POST /threads/:id/resume（Accept 为 SSE 时使用 SSE），并使用 Command({ resume })；始终升级处理 必须发送 approver_id + approver_role；暂停的图 → 终止状态 interrupted

启用用户记忆后 → 使用调用方作用域的 /memories CRUD（references/user-memory.md §5）；user_id 只能来自认证信息。

Brownfield 项目缺少 dev-chat：建议添加 — 不属于 Critical。Postman 与线上路由保持同步。

阶段 7 — 可观测性

按 references/observability.md 配置 initDb、runStorage、logLlmCall、logToolExecution，并持久化 turn_decisions。LangSmith 和 OTel 为可选项。

阶段 8 — 评估与审查

• 按 references/evals-and-gates.md 添加测试套件。
• 在 {agent_api_root} 中运行 npm run build && npm test。
• 对差异调用 ns-reviewer；如果差异涉及 agent-api，要求其检查放置、注入、线上名称和绑定一致性方面的反模式。

维护工作流

持续进行的工作（非 greenfield）：

1. 三项 变更前门槛
2. 变更后，graph-spec.md 与预期图匹配
3. 所属层：图节点、对话、MCP、记忆、HTTP
4. 编辑前阅读对应的参考文档
5. 使用 ns-coder 以最小差异完成变更，并交接放置/注入要求
6. HTTP 路由变更后更新 Postman
7. 重新检查受影响的孤立项清单

MCP 复杂访问（快速规则）

多个 MCP 服务、目录重叠或规模较大时：

• 发现过滤 — 绑定前对 tools/list 应用允许列表
• 本地分类 — read | write | destructive | admin；绝不信任服务端的只读标记
• 单例客户端 — 每个进程只创建一个 MultiServerMCPClient；生产环境中不得按请求创建 stdio
• 传输方式 — 部署使用 Streamable HTTP；stdio 仅用于本地单用户开发
• 错误 — MCP isError: true = 可恢复的 ToolMessage，其 status: "error"；协议故障可能导致请求以 HTTP/SSE failed 中止
• 密钥 — 仅使用 env 或 configurable / 请求载荷；绝不放入 state 或 checkpointer

完整说明：references/mcp-complex-access.md。

交接给 ns-coder

实现获批后，委派以下内容：

## LangGraph implementation task

- Root: {agent_api_root}
- Spec: path/to/graph-spec.md
- Phase: [number and name from this skill]
- target_paths: […]
- layer: […]
- do_not_create_under: […]
- injection_notes: [layers / bind vs auto-inject / caps]
- spec_paths_to_sync: […]
- References to apply: [list]
- Acceptance: build + test pass; orphan checklist items [n] resolved; placement + inject + bind parity verified
- Review: ns-reviewer after tests — must check placement, inject, wire names (`:`), bind parity (load ns-langgraph-agents anti-patterns when diff touches agent-api)

在此继续进行诊断、规格制定、放置、治理设计和 greenfield 引导文案。使用 ns-coder 处理功能差异。版本范围内的功能：ns-spec-driven。

停止条件

条件	操作
没有 graph-spec.md，且用户现在就要代码	创建规范或调用架构师
根据代码片段／其他产品目录组装全新项目	停止；运行 scripts/bootstrap-agent-runtime.mjs
路径不在放置矩阵范围内／要创建新目录	停止；提出合法路径
领域／区域设置／文案被放入 graph/ 或 llm/	停止；改放到对话／配置中
绑定不匹配（可调度但未绑定）	停止；修复绑定，或记录未绑定状态并添加测试
新线缆名称中包含 :	停止；使用 __ 分隔符
技能自动注入与绑定使用相同 ID，但未明确决定	停止；选择一种模式
用户要求 CrewAI	转向合适的技能
变更涉及超过 3 个层级，但没有计划	用一行列出分阶段计划，并等待批准
存在严重安全漏洞（状态中含机密、MCP 未受治理）	阻止功能开发；先修复治理问题

相关技能（职责归属）

技能	职责
ns-langgraph-agents	规范、放置、注入计划、graph-spec、全新项目脚手架
ns-coder	功能差异 + 审查循环（不负责初始脚手架复制）
ns-reviewer	给出结论；当差异涉及 agent-api 时，应用本技能中的放置 + 注入 + 线缆名称 + 绑定匹配反模式
ns-agent-adaptation	架构设计前的概念适配设计
ns-agent-architecture	Phase 0 前的框架选择（未锁定时）
ns-spec-driven	脚手架创建后进行版本功能开发（或将首个任务设为引导初始化）
ns-investigator	运行时调试

禁止事项

• 将规划器的 userFacingIntent 作为 response_streaming 发出，或以 Markdown 形式写入 messages（仅使用 SSE thinking；Composer 仍是唯一的 Markdown 编写者）
• Composer 通过 model.invoke 回复，或在回合结束时一次性输出 response_streaming；缓冲 SSE；客户端打字机效果或延迟绘制事件（references/streaming-and-hitl.md）
• 使用当前用户消息以外的语言编写 userFacingIntent（例如，操作员用葡萄牙语发消息，却用英语报告进度）
• 将组合后的系统/角色提示词（base_invariant + injected）——或密钥/API 密钥——持久化到图状态、检查点或持久化的 messages 中（每次调用时重建系统文本）
• 以 thread_id 作为长期用户记忆的键，将公司/租户事实或密钥存入用户记忆，将渲染后的记忆块持久化到状态/检查点，或要求用户逐条确认记忆，而不是告知用户（references/user-memory.md）
• 将 bootstrap / .env / configurable.locale 视为主要的 locale SoT，或持久化固定的线程 locale（使用从对话中观察到的 turnLocale + Intl）
• 将无界的工具/MCP 输出传入 state.messages
• 将工具/MCP 截断上限应用于技能正文（使用 CONTEXT_SKILL_BODY_MAX_CHARS）
• 信任 MCP 工具元数据进行安全分类
• 在生产环境中为每个 HTTP 请求启动 stdio MCP 子进程
• 让 memory/ 编译 StateGraph
• 将领域限定/对话提示词放在 src/llm/ 中
• 将 locale/呈现逻辑放在 graph/ 下
• 将 Nudge 当作伪造的 HumanMessage
• 将测试放在 src/ 下
• 根据片段或其他产品创建全新目录树——仅使用 templates/agent-runtime/