调用链：

cli.py / core.py / server.py
    └── 调 build_graph()          ← <pkg>/builder.py
            └── import run_node     ← <pkg>/nodes/run.py

/path/to/my-agent/                 ← git 仓库根
├── pyproject.toml
├── .env
├── tests/test_smoke.py
└── my_agent/
    ├── builder.py              ← 组装 LangGraph（与 nodes/ 平级）
    ├── state.py
    ├── core.py                   ← run_agent + telemetry
    ├── cli.py
    ├── server.py
    ├── nodes/
    │   ├── __init__.py
    │   └── run.py              ← 节点业务逻辑（无 builder.py）
    ├── prompts/__init__.py
    ├── specialists/              ← 可选
    └── tools/                      ← 可选

你要做	改这个文件（独立仓完整路径）
节点业务逻辑	my-agent/my_agent/nodes/run.py（或多文件 nodes/scan.py …）
导出新节点	my-agent/my_agent/nodes/__init__.py
串成图 add_node/edge	my-agent/my_agent/builder.py
节点间传什么字段	my-agent/my_agent/state.py
System prompt	my-agent/my_agent/prompts/__init__.py
Portal KPI 指标	my-agent/my_agent/core.py（record_effect）
HTTP pod 入口	my-agent/my_agent/server.py + 根 pyproject.toml 加 fastapi
冒烟测试	my-agent/tests/test_smoke.py
包名 / CLI 命令名	my-agent/pyproject.toml

gov-agents-platform/              ← monorepo 根
├── pyproject.toml                  ← workspace members 加 apps/my-agent
├── packages/gov-agents-server/src/gov_agents_server/main.py
│                                   ← AGENT_REGISTRY + AGENT_META
└── apps/my-agent/
    ├── pyproject.toml              ← BOM extras
    ├── evals/golden.jsonl          ← 评测样本（Monorepo 常有）
    ├── tests/test_smoke.py
    └── my_agent/
        ├── builder.py
        ├── state.py
        ├── server.py               ← build_v1_router（不是 legacy POST）
        ├── specialists.py 或 specialists/  ← 按 scaffold 而定
        └── nodes/ …                  ← 同独立仓

你要做	改这个文件（Monorepo 完整路径）
注册 agent 到平台	gov-agents-platform/pyproject.toml（members） packages/gov-agents-server/src/gov_agents_server/main.py
业务图 / 节点 / state	apps/my-agent/my_agent/builder.py apps/my-agent/my_agent/nodes/*.py apps/my-agent/my_agent/state.py
标准 HTTP API	apps/my-agent/my_agent/server.py
Specialist + prompt	apps/my-agent/my_agent/specialists.py 或 specialists/*.py apps/my-agent/my_agent/prompts/*.md
评测样本	apps/my-agent/evals/golden.jsonl 或 data/eval_samples.jsonl
依赖 / BOM	apps/my-agent/pyproject.toml
IDE MCP 暴露（可选）	packages/gov-agents-mcp/src/gov_agents_mcp/schemas.py

① my_agent/state.py

from typing import Annotated, TypedDict
from operator import add

class AgentState(TypedDict, total=False):
    input: str
    output: str
    retry_count: Annotated[int, add]

② my_agent/nodes/run.py — 只写节点函数

from ai_trust_toolkit.llm import get_llm
from ..state import AgentState

def run_node(state: AgentState) -> AgentState:
    # 你的业务 ...
    return {"output": "..."}

③ my_agent/nodes/__init__.py

from .run import run_node
__all__ = ["run_node"]

④ my_agent/builder.py — 与 nodes/ 平级，负责串图

from langgraph.graph import END, StateGraph
from .nodes import run_node
from .state import AgentState

def build_graph():
    g = StateGraph(AgentState)
    g.add_node("run", run_node)
    g.set_entry_point("run")
    g.add_edge("run", END)
    return g.compile()

场景	文件位置	改什么
调 GitLab / Quickwit / DB	<pkg>/tools/xxx_client.py	只读 client + 脱敏
多 LLM 视角并行	<pkg>/specialists/xxx_sp.py	@sp_node 或工厂节点
长 prompt	<pkg>/prompts/*.md 或 prompts/__init__.py	不要 inline 进 .py
Critic L1 规则	<pkg>/nodes/critic_l1.py 或 builder 注入	Monorepo 常见
自有业务库	<pkg>/governance_store.py（新建）	≠ telemetry 的 core.py