Back to Details

ns-langgraph-agents

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

LangGraph Agents

LangGraph 智能体

Production-grade LangGraph.js (Node 24+, TypeScript strict, 
@langchain/langgraph
).
Owns runtime doctrine — placement, prompt/capability injection, graph-spec sync. Diffs via 
ns-coder
or 
ns-autonomous
. Framework choice: 
ns-multi-agent-architect
.
生产级LangGraph.js（Node 24+、严格模式TypeScript、依赖
@langchain/langgraph
）。
负责运行时准则——文件布局、提示词/能力注入、图规格同步。通过
ns-coder
或
ns-autonomous
实现差异更新。框架选型由
ns-multi-agent-architect
负责。

Applicability

适用场景

ContextDoctrine strength
Greenfield agent-api (new LangGraph runtime)MUST follow build workflow gates — dev-chat, budgets, normalize-before-truncate, separate skill cap. Topology: suggest 
plan_execute
for most MCP/tool-heavy cases — lock in 
graph-spec.md
; not a hard rule
Brownfield existing agentRECOMMENDED migration toward same controls; orphan recovery does not Critical-fail missing topology
Intentional MCP redesignSync 
graph-spec.md
+ refs in same delivery — treat greenfield MUST for topology/budget/evidence sections touched
Brownfield open ReAct valid until deliberate topology change. Greenfield MUST = new agent-api + intentional MCP redesign only.
场景准则严格程度
全新项目agent-api（新LangGraph运行时）必须遵循构建工作流规范——开发对话、预算控制、截断前标准化、技能权限分离。拓扑建议：对于大多数MCP/工具密集型场景，推荐使用
plan_execute
——在
graph-spec.md
中锁定；非强制规则
遗留项目已有智能体建议迁移至相同管控体系；遗留架构恢复时，若缺少拓扑不会导致严重失败
针对性MCP重构同步交付
graph-spec.md
及相关引用——涉及拓扑/预算/验证部分时，需遵循全新项目的强制准则
遗留项目的开放式ReAct模式可继续使用，直至主动变更拓扑。全新项目强制准则仅适用于新agent-api及针对性MCP重构场景。

Routing (read first)

路由规则（必读）

SignalAction
No framework lock / CrewAI requestedStop → 
ns-multi-agent-architect
Orphan / lost structure / layout unclearRun orphan checklist before features (
references/orphan-recovery-checklist.md
)
GitLab 
ISSUE_URL
or SDD version scope		Defer to harness 
../../ns-harness/references/code-skill-routing.md
— do not absorb
Approved placement/inject plan ready for diffHand off to 
ns-coder
for implementation — except greenfield bootstrap copy (
references/bootstrap-agent-runtime.md
)
信号操作
无框架锁定 / 要求使用CrewAI停止 → 调用
ns-multi-agent-architect
架构混乱 / 结构丢失 / 布局不清晰在开发功能前先执行遗留架构恢复清单（
references/orphan-recovery-checklist.md
）
涉及GitLab 
ISSUE_URL
或SDD版本范围		移交至
../../ns-harness/references/code-skill-routing.md
处理——请勿自行承接
已批准的布局/注入方案待实现移交至
ns-coder
执行——全新项目的脚手架复制除外（参考
references/bootstrap-agent-runtime.md
）

Boot (mandatory)

启动流程（强制）

See 
../../ns-harness/references/session-boot.md
— complete Session boot (blocking) there, then:
  1. Confirm 
    {agent_api_root}
    and 
    graph-spec.md
    when touching runtime
  2. Load placement/inject refs before path decisions (
    references/placement-and-domains.md
    , 
    references/prompt-and-capability-injection.md
    )
  3. Continue this skill
Success: placement + inject doctrine + project rules. Failure: invented folders or external frameworks.
参考
../../ns-harness/references/session-boot.md
——**完成会话启动（阻塞式）**后，执行以下步骤：
  1. 处理运行时相关内容时，确认
    {agent_api_root}
    和
    graph-spec.md
    的位置
  2. 进行路径决策前，加载布局/注入相关参考文档（
    references/placement-and-domains.md
    、
    references/prompt-and-capability-injection.md
    ）
  3. 继续使用本技能
成功标准：符合布局+注入准则+项目规则。失败情况：随意创建文件夹或使用外部框架。

When to use

使用场景对应操作

SituationAction
Greenfield agent-api (no 
{agent_api_root}/package.json
)		Build workflow Phase 0 then Phase 1 bootstrap — 
references/bootstrap-agent-runtime.md
Brownfield / orphaned runtimeRun Orphan recovery (
references/orphan-recovery-checklist.md
) before features
New file / unclear folderPlacement Decision Block + 
references/placement-and-domains.md
System prompt / skill inject / bindPrompt/Capability plan + 
references/prompt-and-capability-injection.md
Topology / state / capabilities changeSpec Sync Gate — update 
graph-spec.md
in the same delivery
MCP with many servers/toolsRead 
references/mcp-complex-access.md
+ 
references/capability-governance.md
Token blow-up / slow turnsRead 
references/context-window-and-tokens.md
Provider message/reasoning quirksRead 
references/message-content-blocks.md
HITL / streaming UXRead 
references/streaming-and-hitl.md
JSON planner / analyst chooses toolsOperator-progress channel — 
templates/contracts/planner-contract.md
+ 
references/streaming-and-hitl.md
Evals before mergeRead 
references/evals-and-gates.md
场景操作
全新项目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
拓扑/状态/能力变更执行规格同步检查——在同一交付中更新
graph-spec.md
多服务器/工具的MCP场景阅读
references/mcp-complex-access.md
+ 
references/capability-governance.md
Token超限/响应缓慢阅读
references/context-window-and-tokens.md
服务商消息/推理特性差异阅读
references/message-content-blocks.md
HITL/流式交互体验阅读
references/streaming-and-hitl.md
JSON规划器/分析师选工具遵循操作员进度规范——
templates/contracts/planner-contract.md
+ 
references/streaming-and-hitl.md
合并前评估阅读
references/evals-and-gates.md

Core doctrine

核心准则

LangGraph = control flow. MCP/local tools = capabilities under graph. Small graph state (refs, summaries). Checkpointer = full state; context window = LLM view — separate.
System prompt: compose 
base_invariant
(motor) + 
injected
(product persona) per LLM invoke. Never persist composed system/persona text in graph state, checkpointer, or durable 
messages
. Summary 
SystemMessage
at index 0 ≠ full system — 
references/prompt-and-capability-injection.md
, 
references/message-content-blocks.md
.
Locale: conversation-observed 
turnLocale
(detection-first from human messages ± intent slots); 
configurable.locale
weak hint only; Intl formatters in code — not fixed bootstrap locale. 
references/evidence-and-fidelity.md
, 
templates/snippets/conversation-locale.ts.snippet
.
Operator progress (JSON planner hops): greenfield 
streaming_sse
with a planner/analyst that emits structured 
executionPlan
(no 
bindTools
on that hop) MUST persist 
userFacingIntent
(or 
analysis.userFacingIntent
) + 
executionPlan
on 
AgentState
. 
userFacingIntent
language MUST match the current user message (last 
HumanMessage
) — not English unless that message is English; not product default locale. Machine 
intent
stays English for audit. Emit SSE 
thinking
from that field at node entry of the next hop — not 
response_streaming
, not in durable 
messages
. Hop 0 uses generic copy from 
conversation/presentation/
(or locale) in the same operator language. Open ReAct + 
ToolNode
uses 
tool_started
/ 
tool_finished
only. Details: 
templates/contracts/planner-contract.md
, 
references/streaming-and-hitl.md
.
Three capability kinds bind to the model:
KindLLM wire nameInternal id
Local tool
{name}
local:{name}
MCP tool
mcp__{server}__{tool}
mcp:{server}:{tool}
Skill procedure
use_skill__{id}
skill:{id}
Wire names must match 
^[a-zA-Z0-9_-]{1,128}$
(use 
__
separators; colons only in internal ids). Colon in a new wire name is Critical on review.
LangGraph = 控制流。MCP/本地工具 = 图管控下的能力。图状态应精简（引用、摘要）。检查点工具 = 完整状态；上下文窗口 = LLM可见范围——两者需分离。
系统提示词：每次调用LLM时，组合
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可使用冒号）。新绑定名称中出现冒号会导致评审不通过。

Pre-change gates

变更前检查

Before new file or inject/bind change: complete all three. No code until posted.
新建文件或修改注入/绑定前：完成以下三项检查。未提交检查结果前请勿编写代码。

1. Placement Decision Block

1. 布局决策检查

markdown
undefined
markdown
undefined

Placement Decision Block

布局决策检查

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

Full matrix: `references/placement-and-domains.md`.
  • 产物: …
  • 类型: …
  • 目标路径: …
  • 层级: …
  • 参考文档: placement-and-domains.md
  • 禁止创建路径: […]

完整矩阵参考`references/placement-and-domains.md`。

2. Prompt / Capability plan

2. 提示词/能力方案

markdown
undefined
markdown
undefined

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: […]

Full doctrine: `references/prompt-and-capability-injection.md`.
  • 组合方式: base_invariant + injected（每次调用时重构；不存入状态/检查点/持久化messages）
  • 核心规则(
    base_invariant
    ): [禁止Markdown收集 / 单一输出者 / 工具使用规范 / JSON规划器userFacingIntent仅用于SSE而非Markdown / …]
  • 产品配置(
    injected
    ): 标准路径 + 角色/语气说明；模式解析: 是/否；模式列表: [...]; 解析器: ...
  • 涉及系统层级: […]
  • 标准提示词路径: …
  • 会话覆盖: 是/否
  • 绑定列表: […]
  • 自动注入技能: […]（与同ID的绑定互斥）
  • 截断规则: 工具 vs 技能主体
  • 绑定一致性: …
  • 需同步的规格路径: […]

完整准则参考`references/prompt-and-capability-injection.md`。

3. Spec Sync Gate

3. 规格同步检查

Nodes, edges, state, capabilities, recursion_limit, or wire names change: update 
graph-spec.md
same delivery. Stale archive ≠ SoT — sync spec to intended runtime; do not force-fit live code to stale archive.
节点、边、状态、能力、递归限制或绑定名称变更时：在同一交付中更新
graph-spec.md
。过时归档文件不视为可信来源——需将规格同步至预期运行时；请勿强行让现有代码适配过时归档。

Reference map

参考文档映射

Load on demand — do not memorize whole files.
ReferenceRead when
references/bootstrap-agent-runtime.md
Greenfield copy of 
templates/agent-runtime/
references/orphan-recovery-checklist.md
Project structure unclear or agent "lost"
references/runtime-layout.md
Scaffolding, refactors, layer violations
references/placement-and-domains.md
Where to put files; domain vs graph vs config
references/prompt-and-capability-injection.md
System prompt layers, bind vs inject, bind parity
references/message-content-blocks.md
AIMessage/HumanMessage/ToolMessage across providers
references/context-window-and-tokens.md
trim, summarize, tool vs skill body caps, 
context_manager
references/mcp-complex-access.md
Multi-server MCP, discovery, transport, lifecycle
references/capability-governance.md
Allowlist, classification, rate limits, tool budgets
references/evidence-and-fidelity.md
State-backed evidence, fidelity gate, conversation-observed locale
templates/snippets/conversation-locale.ts.snippet
resolveConversationLocale
+ Intl 
formatUserFacing
templates/snippets/tool-budget.ts.snippet
Per-turn tool/MCP caps, arg fingerprint duplicate-skip
templates/snippets/prepare-llm-messages.ts.snippet
context_manager
helper
references/error-and-reliability.md
Tool errors, circuit breaker, retries
references/observability.md
Postgres audit, LangSmith, OTel, run context
references/architectures.md
ReAct, plan_execute (suggested start for most MCP), other topologies; node id ≠ state channel
references/streaming-and-hitl.md
SSE envelopes, operator 
thinking
from planner state, 
interrupt()
, 
Command
resume
templates/contracts/planner-contract.md
JSON planner hops: 
executionPlan
+ 
userFacingIntent
references/evals-and-gates.md
Architecture, tool-selection, memory evals
references/anti-patterns.md
Review gate before marking done
Templates: 
templates/agent-runtime/
(greenfield tree), 
templates/graph-spec.md
, 
templates/contracts/
, 
templates/snippets/
(brownfield patches).
按需加载——无需记忆完整文档内容。
参考文档使用场景
references/bootstrap-agent-runtime.md
从
templates/agent-runtime/
复制全新项目脚手架
references/orphan-recovery-checklist.md
项目结构不清晰或智能体「失控」时
references/runtime-layout.md
脚手架搭建、重构、层级违规检查
references/placement-and-domains.md
文件存放位置；领域/图/配置的划分
references/prompt-and-capability-injection.md
系统提示词层级、绑定vs注入、绑定一致性
references/message-content-blocks.md
不同服务商的AIMessage/HumanMessage/ToolMessage处理
references/context-window-and-tokens.md
裁剪、摘要、工具vs技能主体限制、
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/observability.md
Postgres审计、LangSmith、OTel、运行上下文
references/architectures.md
ReAct、plan_execute（大多数MCP场景推荐起始拓扑）、其他拓扑；节点ID ≠ 状态通道
references/streaming-and-hitl.md
SSE信封格式、操作员
thinking
事件从规划器状态获取、
interrupt()
、
Command
恢复
templates/contracts/planner-contract.md
JSON规划器步骤：
executionPlan
+ 
userFacingIntent
references/evals-and-gates.md
架构、工具选择、内存评估
references/anti-patterns.md
标记完成前的评审检查
模板路径：
templates/agent-runtime/
（全新项目目录）、
templates/graph-spec.md
、
templates/contracts/
、
templates/snippets/
（遗留项目补丁）。

Session inputs

会话输入

VariableRequired
{agent_api_root}
Default 
agent-api
{task}
What to build, fix, or review
变量必填
{agent_api_root}
默认值
agent-api
{task}
需构建、修复或评审的内容

Orphan recovery (brownfield first)

遗留架构恢复（优先处理）

Runtime disorganized or team blocked:
  1. Read 
    references/orphan-recovery-checklist.md
    ; score project.
  2. Gap report: structure, placement, context window, inject/bind parity, MCP governance, HTTP, spec sync.
  3. Ordered fix plan (one phase per message if large).
  4. Implement via 
    ns-coder
    .
No new graph nodes or MCP servers until layout + governance baselines pass.
运行时混乱或团队受阻时：
  1. 阅读
    references/orphan-recovery-checklist.md
    ；为项目评分。
  2. 生成差距报告：结构、布局、上下文窗口、注入/绑定一致性、MCP管控、HTTP、规格同步。
  3. 制定有序修复计划（大型项目可分阶段提交）。
  4. 通过
    ns-coder
    执行修复。
布局+管控基线达标前，请勿新增图节点或MCP服务器。

Build workflow (greenfield or post-recovery)

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

Phase 0 — Spec gate

第0阶段 — 规格检查

If 
graph-spec.md
is missing, create it from 
templates/graph-spec.md
. Minimum sections: locked header (
framework
, 
architecture
, 
interaction_mode
), domain ownership, prompt composition, state schema, nodes table, edges, interrupts, memory, capability bind/inject table, recursion_limit, HTTP routes.
If the user has no architecture decision yet, stop and invoke 
ns-multi-agent-architect
first.
若缺少
graph-spec.md
，从
templates/graph-spec.md
创建。必填章节：锁定头部（
framework
、
architecture
、
interaction_mode
）、领域归属、提示词组合、状态 schema、节点表、边、中断、内存、能力绑定/注入表、递归限制、HTTP路由。
若用户尚未确定架构决策，停止当前操作并先调用
ns-multi-agent-architect
。

Phase 1 — Skeleton

第1阶段 — 骨架搭建

If 
{agent_api_root}/package.json
is missing, run 
scripts/bootstrap-agent-runtime.mjs
(
references/bootstrap-agent-runtime.md
). Then 
npm install && npm test
in 
{agent_api_root}
.
Do not assemble the tree from 
templates/snippets/
. Do not copy another product. After copy: align 
src/graph/
with 
graph-spec.md
; put domain in 
conversation/
+ 
config/
via later phases / 
ns-coder
.
Brownfield existing tree: align per 
references/runtime-layout.md
— snippets for patches only.
若缺少
{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
对齐——仅使用补丁片段。

Phase 2 — State and persistence

第2阶段 — 状态与持久化

After bootstrap, verify these exist; do not re-scaffold. Fill only gaps vs 
graph-spec.md
.
  • AgentState
    with 
    messages
    reducer (
    Annotation.Root
    or Zod + 
    MessagesZodMeta
    ).
  • PostgresSaver
    in dev/prod; 
    MemorySaver
    only in 
    tests/setup.ts
    .
  • Every invoke/stream: 
    configurable.thread_id
    via 
    buildRunConfig
    .
  • JSON planner/analyst (no 
    bindTools
    on that hop): declare 
    executionPlan
    + 
    userFacingIntent
    (or nested on 
    analysis
    ) in 
    graph-spec.md
    state schema — 
    templates/snippets/state.ts.snippet
    .
脚手架搭建完成后，验证以下内容是否存在；请勿重新搭建。仅补充与
graph-spec.md
的差距部分。
  • 带
    messages
    reducer的
    AgentState
    （
    Annotation.Root
    或Zod + 
    MessagesZodMeta
    ）。
  • 开发/生产环境使用
    PostgresSaver
    ；仅在
    tests/setup.ts
    中使用
    MemorySaver
    。
  • 每次调用/流式传输：通过
    buildRunConfig
    传入
    configurable.thread_id
    。
  • JSON规划器/分析师（该步骤不绑定
    bindTools
    ）：在
    graph-spec.md
    的状态 schema 中声明
    executionPlan
    + 
    userFacingIntent
    （或嵌套在
    analysis
    中）——参考
    templates/snippets/state.ts.snippet
    。

Phase 3 — LLM and messages

第3阶段 — LLM与消息

  • Provider config in 
    src/llm/
    (infra only — no domain prompts).
  • Prefer JSON mode + Zod parse for structured turns; avoid 
    withStructuredOutput
    on OpenAI-compatible local servers.
  • Normalize provider output via 
    contentBlocks
    / 
    content_blocks
    — see 
    references/message-content-blocks.md
    .
  • 服务商配置放在
    src/llm/
    （仅基础设施配置——无领域提示词）。
  • 结构化交互优先使用JSON模式+Zod解析；OpenAI兼容的本地服务器避免使用
    withStructuredOutput
    。
  • 通过
    contentBlocks
    / 
    content_blocks
    标准化服务商输出——参考
    references/message-content-blocks.md
    。

Phase 4 — Context window (mandatory)

第4阶段 — 上下文窗口（强制）

Implement per 
references/context-window-and-tokens.md
:
  • trimMessagesForLlm
    before every LLM call.
  • normalizeMcpToolResult
    then 
    truncateToolOutput
    before 
    ToolMessage
    enters state.
  • Separate 
    CONTEXT_SKILL_BODY_MAX_CHARS
    for skill bodies (snippet 
    skillBodyMaxChars
    ).
  • Optional 
    summarizeOlderMessages
    with persisted compaction (
    RemoveMessage
    + rewrite) in the same agent-node return.
Never pass raw 
state.messages
to the model.
参考
references/context-window-and-tokens.md
实现：
  • 每次调用LLM前执行
    trimMessagesForLlm
    。
  • ToolMessage
    进入状态前，先执行
    normalizeMcpToolResult
    再执行
    truncateToolOutput
    。
  • 技能主体使用独立的
    CONTEXT_SKILL_BODY_MAX_CHARS
    限制（参考片段
    skillBodyMaxChars
    ）。
  • 可选：使用
    summarizeOlderMessages
    并在同一智能体节点返回中执行持久化压缩（
    RemoveMessage
    + 重写）。
切勿将原始
state.messages
直接传入模型。

Phase 5 — Capabilities

第5阶段 — 能力集成

  1. Local 
    StructuredTool
    s in 
    src/tools/
    .
  2. MCP: governed client — discovery → local allowlist → wire names → singleton client lifecycle (
    references/mcp-complex-access.md
    ).
  3. Skills: 
    skills/*.md
    auto-discovered → 
    use_skill__{id}
    or auto-inject (exclusive per id).
Apply 
references/capability-governance.md
and 
references/prompt-and-capability-injection.md
before 
bindTools
. Enforce bind parity. Wire per-turn tool/MCP budgets from 
templates/snippets/tool-budget.ts.snippet
when MCP or external tools are bound.
  1. 本地
    StructuredTool
    放在
    src/tools/
    。
  2. MCP：管控型客户端——服务发现 → 本地白名单 → 绑定名称 → 单例客户端生命周期（参考
    references/mcp-complex-access.md
    ）。
  3. 技能：
    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调用预算限制。

Phase 6 — HTTP and interaction mode

第6阶段 — HTTP与交互模式

ModeRequirements
sync_json
POST /threads
, 
POST /threads/:id/message
streaming_sse
SSE envelope per 
references/streaming-and-hitl.md
; greenfield MUST ship 
GET /dev-chat
gated by 
DEV_CHAT_ENABLED
(local-only); JSON planner hops MUST emit operator 
thinking
from state 
userFacingIntent
HITL
interrupt()
+ 
POST /threads/:id/resume
with 
Command({ resume })
Brownfield missing dev-chat: recommend add — not Critical. Postman synced with live routes.
模式要求
sync_json
实现
POST /threads
、
POST /threads/:id/message
streaming_sse
遵循
references/streaming-and-hitl.md
的SSE信封格式；全新项目必须提供由
DEV_CHAT_ENABLED
管控的
GET /dev-chat
接口（仅本地可用）；JSON规划器步骤必须从状态
userFacingIntent
发送操作员
thinking
事件
HITL实现
interrupt()
+ 
POST /threads/:id/resume
接口，支持
Command({ resume })
遗留项目缺少dev-chat接口：建议添加——非强制要求。Postman需与当前路由同步。

Phase 7 — Observability

第7阶段 — 可观测性

Wire 
references/observability.md
: 
initDb
, 
runStorage
, 
logLlmCall
, 
logToolExecution
, persist 
turn_decisions
. LangSmith and OTel are opt-in.
对接
references/observability.md
：
initDb
、
runStorage
、
logLlmCall
、
logToolExecution
、持久化
turn_decisions
。LangSmith和OTel为可选配置。

Phase 8 — Evals and review

第8阶段 — 评估与评审

  • Add suites per 
    references/evals-and-gates.md
    .
  • Run 
    npm run build && npm test
    in 
    {agent_api_root}
    .
  • Invoke 
    ns-reviewer
    on the diff; ask it to verify placement, inject, wire-name, and bind-parity anti-patterns when the diff touches 
    agent-api
    .
  • 参考
    references/evals-and-gates.md
    添加测试套件。
  • 在
    {agent_api_root}
    目录下执行
    npm run build && npm test
    。
  • 调用
    ns-reviewer
    评审差异；当差异涉及
    agent-api
    时，要求其验证布局、注入、绑定名称、绑定一致性等反模式问题。

Maintenance workflow

维护工作流

Ongoing work (not greenfield):
  1. Three Pre-change gates
  2. graph-spec.md
    matches intended graph after change
  3. Layer: graph node, conversation, MCP, memory, HTTP
  4. Read matching reference before edit
  5. Minimal diff via 
    ns-coder
    with placement/inject handoff
  6. Postman on HTTP route change
  7. Re-run orphan checklist items touched
日常维护（非全新项目）：
  1. 完成三项变更前检查
  2. 变更后
    graph-spec.md
    需与预期图一致
  3. 层级分类：图节点、对话、MCP、内存、HTTP
  4. 编辑前阅读对应参考文档
  5. 通过
    ns-coder
    实现最小化差异，并移交布局/注入相关内容
  6. HTTP路由变更时同步Postman
  7. 重新运行涉及的遗留架构恢复清单项

MCP complex access (quick rules)

MCP复杂访问（快速规则）

Multiple MCP servers, overlapping or large catalogs:
  • Discovery filter — allowlisted 
    tools/list
    before bind
  • Local classify — 
    read | write | destructive | admin
    ; never trust server read-only flags
  • Singleton client — one 
    MultiServerMCPClient
    per process; no per-request stdio in prod
  • Transport — Streamable HTTP deployed; stdio local single-user dev only
  • Errors — MCP 
    isError: true
    = recoverable 
    ToolMessage
    status: "error"
    ; protocol fail may abort with HTTP/SSE 
    failed
  • Secrets — env or 
    configurable
    / request payload only; never state or checkpointer
Full: 
references/mcp-complex-access.md
.
多MCP服务器、工具目录重叠或规模较大时：
  • 服务发现过滤 — 绑定前先通过白名单过滤
    tools/list
  • 本地分类 — 标记
    read | write | destructive | admin
    ；切勿信任服务器的只读标记
  • 单例客户端 — 每个进程仅实例化一个
    MultiServerMCPClient
    ；生产环境禁止为每个请求生成stdio子进程
  • 传输方式 — 部署流式HTTP；stdio仅用于本地单用户开发
  • 错误处理 — MCP返回
    isError: true
    = 可恢复的
    ToolMessage
    ，标记
    status: "error"
    ；协议失败可能导致HTTP/SSE返回
    failed
    并终止
  • 密钥管理 — 仅通过环境变量或
    configurable
    /请求载荷传递；切勿存入状态或检查点
完整规则参考
references/mcp-complex-access.md
。

Handoff to ns-coder

移交至ns-coder

When implementation is approved, delegate with:
markdown
undefined
方案获批后，按以下格式移交任务：
markdown
undefined

LangGraph implementation task

LangGraph实现任务

  • 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)

Stay here for diagnosis, spec, placement, governance design, and **greenfield bootstrap copy**. `ns-coder` for feature diffs. Version-scoped features: `ns-spec-driven`.
  • 根目录: {agent_api_root}
  • 规格文档: path/to/graph-spec.md
  • 阶段: [本技能中的阶段编号及名称]
  • 目标路径: […]
  • 层级: […]
  • 禁止创建路径: […]
  • 注入说明: [层级 / 绑定vs自动注入 / 限制]
  • 需同步的规格路径: […]
  • 需应用的参考文档: [列表]
  • 验收标准: 构建+测试通过；遗留架构恢复清单第[n]项已解决；布局+注入+绑定一致性已验证
  • 评审: 测试通过后调用ns-reviewer——当差异涉及agent-api时，需检查本技能中提到的布局、注入、绑定名称（
    :
    ）、绑定一致性等反模式

本技能负责诊断、规格制定、布局设计、管控方案设计，以及**全新项目脚手架复制**。`ns-coder`负责功能差异实现。版本化功能由`ns-spec-driven`负责。

Stop conditions

停止条件

ConditionAction
No 
graph-spec.md
and user wants code now		Create spec or invoke architect
Greenfield assembled from snippets / another product treeStop; run 
scripts/bootstrap-agent-runtime.mjs
Path outside placement matrix / inventing foldersStop; propose legal path
Domain / locale / copy landing in 
graph/
or 
llm/
Stop; reroute to conversation/config
Bind without parity (dispatchable but unbound)Stop; fix bind or document unbound + test
:
in a new wire name		Stop; use 
__
separators
Skill auto-inject + bind same id without explicit decisionStop; choose one mode
CrewAI requestedRedirect to appropriate skill
Change spans >3 layers without planOne-line phased plan, wait for approval
Critical security gap (secrets in state, ungoverned MCP)Block feature work; fix governance first
条件操作
缺少
graph-spec.md
且用户要求立即编写代码		创建规格文档或调用架构选型工具
全新项目从片段/其他项目组装目录树停止；运行
scripts/bootstrap-agent-runtime.mjs
路径超出布局矩阵范围/随意创建文件夹停止；提出合规路径方案
领域/区域设置/文本放入
graph/
或
llm/
目录		停止；重新路由至conversation/config目录
绑定不一致（可调度但未绑定）停止；修复绑定或记录未绑定情况并测试
新绑定名称中包含
:
停止；使用
__
分隔
同一ID同时启用技能自动注入+绑定且未明确决策停止；选择其中一种模式
要求使用CrewAI重定向至对应技能
变更涉及超过3个层级且无方案制定分阶段计划，等待批准
严重安全漏洞（状态中存储密钥、MCP无管控）暂停功能开发；优先修复管控问题

Related skills (ownership)

关联技能（职责划分）

SkillOwns
ns-langgraph-agents
Doctrine, placement, inject plan, graph-spec, greenfield scaffold
ns-coder
Feature diffs + review loop (not initial scaffold copy)
ns-reviewer
Verdict; when diff touches 
agent-api
, apply placement + inject + wire-name + bind-parity anti-patterns from this skill
ns-multi-agent-architect
Framework choice before Phase 0 when unlocked
ns-spec-driven
Version features after scaffold exists (or first task = bootstrap)
ns-investigator
Runtime debug
技能职责
ns-langgraph-agents
准则制定、布局设计、注入方案、图规格、全新项目脚手架
ns-coder
功能差异实现+评审循环（不包含初始脚手架复制）
ns-reviewer
评审结论；当差异涉及
agent-api
时，检查本技能中的布局、注入、绑定名称、绑定一致性等反模式
ns-multi-agent-architect
未锁定框架时，第0阶段前的框架选型
ns-spec-driven
脚手架搭建完成后的版本化功能管理（或首个任务为脚手架搭建）
ns-investigator
运行时调试

Forbidden

禁止操作

  • Emitting planner 
    userFacingIntent
    as 
    response_streaming
    or as Markdown in 
    messages
    (SSE 
    thinking
    only; composer remains sole Markdown writer)
  • Writing 
    userFacingIntent
    in a language other than the current user message (e.g. English progress when the operator wrote Portuguese)
  • Persisting composed system/persona prompt (
    base_invariant + injected
    ) — or secrets/API keys — in graph state, checkpointer, or durable 
    messages
    (rebuild system text per invoke)
  • Treating bootstrap / 
    .env
    / 
    configurable.locale
    as primary locale SoT, or persisting sticky thread locale (use conversation-observed 
    turnLocale
    + Intl)
  • Passing unbounded tool/MCP output into 
    state.messages
  • Applying tool/MCP truncate caps to skill bodies (use 
    CONTEXT_SKILL_BODY_MAX_CHARS
    )
  • Trusting MCP tool metadata for security classification
  • Spawning stdio MCP subprocesses per HTTP request in production
  • memory/
    compiling 
    StateGraph
  • Domain qualify/conversation prompts in 
    src/llm/
  • Locale/presentation under 
    graph/
  • Nudge as fake 
    HumanMessage
  • Tests under 
    src/
  • Greenfield tree from snippets or another product — use 
    templates/agent-runtime/
    only
  • 将规划器
    userFacingIntent
    作为
    response_streaming
    发送，或写入
    messages
    作为Markdown（仅允许作为SSE 
    thinking
    事件；输出文本仅由专属模块编写Markdown）
  • userFacingIntent
    使用与当前用户消息不同的语言（例如操作员发送葡萄牙语，却输出英文进度）
  • 持久化组合后的系统/角色提示词（
    base_invariant + injected
    ）——或密钥/API密钥——到图状态、检查点或持久化
    messages
    （每次调用时重新构建系统文本）
  • 将脚手架/
    .env
    /
    configurable.locale
    作为区域设置的主要可信来源，或持久化会话固定区域设置（使用对话检测的
    turnLocale
    + Intl）
  • 将无限制的工具/MCP输出写入
    state.messages
  • 对技能主体应用工具/MCP截断规则（使用
    CONTEXT_SKILL_BODY_MAX_CHARS
    ）
  • 信任MCP工具元数据进行安全分类
  • 生产环境中为每个HTTP请求生成stdio MCP子进程
  • 在
    memory/
    目录中编译
    StateGraph
  • 在
    src/llm/
    中存放领域/对话提示词
  • 在
    graph/
    目录下存放区域设置/展示相关内容
  • 将引导消息伪装成
    HumanMessage
  • 在
    src/
    目录下存放测试用例
  • 从片段或其他项目构建全新项目目录树——仅允许使用
    templates/agent-runtime/