从skill到plugin: 依赖于Hook+seesion SDK的功能性增强版本 Task-Loop

Task-Loop v1.2.0：从提示词约束到 Plugin & Hook 物理硬治理------通用任务循环架构实践(依旧基于会话间调用)

$!IMPORTANT$
$版本演进前置声明 / Architectural Evolution Note$

本文是基于上一版《AI开发实践: 项目记忆 + 完整的debug/dev 开发工作流的结合》（v1.0.0）的重大架构升级篇（v1.2.0 Plugin 强化版） 。https://blog.csdn.net/jingjiaohuan/article/details/163952053

本版本在保持"主中枢调度、长周期专题会话、任务循环闭环与受控记忆沉淀"核心思想不变的前提下，完成了从单一 Skill（提示词软约束）向标准 Plugin 插件包体系与 Hook 生命周期物理硬治理的根本性跨越。

摘要 (Abstract)

在基于大语言模型的 AI 辅助研发实践中，初期团队往往通过编写 System Prompt 或 Agent Skill（如 AGENTS.md / SKILL.md）对智能体进行流程规范与边界引导。然而随着中大型工程演进，纯提示词维度的"软约束"逐渐暴露出三大致命瓶颈：

指令注意力漂移与遗忘：多轮对话后，模型对前置提示词约束的遵从度不可避免地出现衰减；
源码与配置文件污染 ：为了注入会话状态或动态规则，往往需要侵入式修改用户代码库中的 AGENTS.md 或文本文件；
物理越界无法阻断：提示词无法在操作系统与工具调用层真正阻断越权文件写入与破坏性操作。

针对上述工业级痛点，基于上一版的skill文档 ,Task-Loop v1.2.0 架构迎来了体系化升维：深度融合 某歌某重力 (AGY) Plugin 插件体系与生命周期钩子（Hooks）拦截引擎 ，将主调度中枢拆解为 5 大高内聚专业 Skill，实现了 PreInvocation 瞬态零污染规则注入与 PreToolUse 白名单物理硬门禁拦截，同时构建了兼容 OpenAI Codex 与 Anthropic Claude Code 的跨厂商统一会话控制层（SessionProvider）。当然当前Agent拓展工具的核心思想依然没变, 围绕着会话进行长期持久会话, 通过调用Seession sdk 充分地利用上下文和缓存资源, 缩减AI工作范围.

一、架构演进：从"提示词软引导"到"插件级物理硬治理"

text 复制代码

[v1.0.0 纯 Skill 提示词阶段]                 [v1.2.0 Plugin & Hook 硬治理阶段]
┌──────────────────────────────┐              ┌──────────────────────────────────────────┐
│  单一 SKILL.md 大文件         │   架构演进   │  标准 某重力 Plugin 插件包体系      │
│  - 纯 Markdown 提示词引导     │ ───────────► │  - 5 大独立专属 Skill 模块化矩阵          │
│  - 依赖模型自发遵守规则       │              │  - PreInvocation 瞬态上下文注入 (零污染) │
│  - 容易发生修改越界           │              │  - PreToolUse 白名单物理硬门禁 (Deny)    │
│  - 静态修改侵入 AGENTS.md    │              │  - 领域管辖权优先于复杂度 (Domain Owner) │
└──────────────────────────────┘              └──────────────────────────────────────────┘

核心演进对比

架构维度	v1.0.0 纯 Skill 阶段	v1.2.0 Plugin & Hook 强化版
存在形态	单一 `SKILL.md` 提示词指令	标准某重力 Plugin 包 (`plugin.json` / `hooks.json`)
规则注入介质	静态修改用户项目 `AGENTS.md`	`PreInvocation` 钩子瞬态注入 (`ephemeralMessage`)，零文件污染
边界防护能力	提示词声明 Allowlist（弱防护）	`PreToolUse` 拦截引擎匹配物理白名单，越界直接 `decision: deny`
会话治理颗粒度	单一技能混合处理所有职责	5 大专业独立 Skill 矩阵（`task-loop`, `hook`, `session-control`, `subagent`, `init`）
领域协作铁律	按任务复杂度判定处理层级	领域管辖权绝对优先于复杂度（专属性资产改动必须派发对应专题会话）
老项目接入成本	人工梳理历史会话	`init` 技能全自动只读扫描、启发式映射推断与交互式 `--dry-run` 预览

二、5 大独立专业 Skill 矩阵与 SVG 架构深度解构

在 v1.2.0 中，系统根据单一职责原则（SRP）将调度治理能力拆分为 5 个相互解耦、专业分工的 Skill。以下结合专属定制的 SVG 架构与流程图进行深度解构：

1. `task-loop`：主中枢任务循环与分级派单流程 (Process Flow)

task-loop 负责主会话层面的全局需求受理工序、任务二元定界、专题相似度防冲突比对、三步派单与质检验收门禁。

核心机制与铁律：

主会话"不干活"：主会话专职于"需求初加工、任务编排、专题相似度匹配、白名单(修改范围)划定与质检验收"，所有代码落地更改一律派发至对应专题会话；
任务下发声明 ：下任务报文的头部,强制声明任务类型为只读探索 [EXPLORE] 还是修改落地 [WORK]；
前置相似度比对 ：派单前强制检索既有专题库（modules / tags / docs/memory），复用优先，严禁重复创建重叠业务冲突专题；
标准三步派单法 ：
1. 寻找已有长期专题；
2. 若无对应领域专题，调用 agentapi new-conversation 创建真实持久顶层专题会话；
3. 通过 send_message 定向发信，划定物理 allowlist 白名单；
1/2/3 复杂度分级调度 ：
- Level 1 (内部闭环)：极简查询/只读诊断，快速响应；
- Level 2 (标准下发)：领域专题会话独立自测、回写受控记忆与结构化交付；
- Level 3 (Subagent 并行)：拉起多代理+沙箱，并行推进 Research(Explore) / Worker / Reviewer。

2. `hook`：生命周期拦截机制 & 物理安全门禁 (Architecture & Logic)

hook 技能实现了某歌某重力(这里以agy为例) 原生生命周期钩子体系的封装，彻底告别了不可靠的"提示词口头防线"，建立了真正的物理隔离硬门禁。

核心实现亮点：

PreInvocation 瞬态会话上下文注入 ：
- 拦截模型调用前置事件，从 stdin 读取当前会话 UUID，精准匹配 sessions.json；
- 输出 { ephemeralMessage: "..." } 瞬态消息，零历史气泡污染、零 Token 轮询、零修改源码或 AGENTS.md；
- 在源头将 [Plugin: task-loop] 业务属性与 [Global Rules] 全局规范物理隔离；
- 支持 enable_footer_hook_dump: false 默认关闭与环境变量 $env:ENABLE_HOOK_PROMPT_DUMP 随时手动切换。
PreToolUse 白名单物理拦截门禁 ：
- 原生拦截 write_to_file、replace_file_content、run_command 等修改工具；
- 提取目标路径并执行 Windows 路径归一化，与派单 task.allowlist 进行严格比对；
- 白名单内放行 { decision: "allow" }，发生越界修改直接拦截 { decision: "deny" }，彻底杜绝代码破坏。

补充: 我很早就像干这个事儿了, 受不了什么规则都往AGENTS.md里面放, 导致阅读性极差, 其实绝大部分的约束规范我们加上就不再关心了, 不如直接使用hook 强制注入到上下文中, 避免再走一遍全局规则(AGENTS.md 当然会有更高的权重,我相信大部分harness 工具提供商都是这样的, 因此使用hook的机制时候, 注意上下文注入的时候,强调其重要性和范围)

3. `session-control`：跨 $平台/工具$ 的会话控制与反向内省 (Architecture & Topology)

session-control 负责跨厂商智能体(某x,某code,某重力)会话抽象、反向日志内省与生命周期统一管理。

图 3：跨厂商日志内省、SessionProvider 六大原语与状态拓扑架构图

核心机制：

跨厂商日志内省引擎 ：
- AGY ：解析 $AppDataDir/brain/<uuid>/.system_generated/logs/transcript.jsonl；
- Codex ：解析 ~/.codex/sessions/*.json 与 CODEX_THREAD_ID；
- Claude Code ：通过 --resume / claude agents --json 提取会话状态；
SessionProvider 六大标准原语 ：
1. get_current_session_id: 获取当前运行时会话 ID
2. scan_project_sessions: 扫描当前工作区所有历史会话
3. spawn_topic_session: 派生或创建顶层专题会话
4. send_message: 跨会话定向发信
5. manage_subagents: 状态检查与超时熔断回收
6. await_reply: 异步响应挂起
状态拓扑与受控记忆 ：维护 .agents/task-loop/sessions.json、topics.json 与 docs/memory/session_control.md。

4. `subagent`：原生子代理编排与生命周期流程 (Process Flow)

subagent 专注于 某重力 原生子代理原语治理、动态模板声明与多代理并行协作。

图 4：原生子代理动态模板声明、工作区物理隔离与被动唤醒生命周期图

核心机制：

原生原语封装 ：规范 invoke_subagent、define_subagent、manage_subagents 调用签名，支持 Python SDK SubagentConfig 工具动态注入；
工作区物理隔离模式 (Workspace Isolation) ：
- inherit：继承主工作区（只读或协同场景）；
- branch：独立物理克隆副本（高风险改动与重构）；
- share：Worktree 共享底层存储（轻量分支隔离）；
Reactive Wakeup 被动唤醒机制 ：
- 子代理在后台异步运行，主进程严禁死循环轮询 status；
- 系统事件自动唤醒主进程，实现零 Token 消耗挂机等待；
即时资源回收 ：任务交付后立即调用 manage_subagents(Action='kill') 释放工作区与内存。

5. `init`：老项目接入与已有会话调查流程 (Onboarding Flow)

在新项目接入 task-loop 插件时，init 提供了平滑的无侵入式历史会话梳理与交互式确认方案。

图 5：老项目历史会话只读扫描、启发式推断与用户兜底修改流程图

核心机制：

无侵入扫描与启发式推断 ：全自动扫描当前工程中所有历史会话（无论命名差异多大），提取原标题与交互关键词，智能推断标准专题名、module_key 与记忆文档路径；
--dry-run 用户交互预览：以结构化清单向用户呈现建议映射表，允许用户按意图进行裁决与微调；
状态机一键落盘 ：写入 .agents/task-loop/sessions.json 与 topics.json；
明确物理路径与用户兜底修改 ：在终端明确打印 sessions.json 绝对路径。若用户发现专题划分不符合预期，随时可直接手动编辑底层 JSON，插件实时热加载生效。

三、关键工程治理铁律 (Governance Hard Rules)

1. 领域管辖权绝对优先于复杂度 (Domain Ownership Trumps Complexity)

在以往的协同中，常出现"因为改动只有 1 行代码，主会话或通用会话就顺手修改了"的现象，导致专题会话上下文断层。

task-loop 确立了铁律：

凡属专属领域专题（hook / session_control / subagent / init）管辖范围的资产，无论改动多么微小，严禁主会话或其他非管辖会话就地修改！
必须通过 send_message 派发给对应的专题负责人执行，由其更新受控记忆文档，确保信息认知链路 100% 闭环。

2. 纯净持久化格式与自然对话排版分界

项目内部持久化 *.md 文档 （如 docs/memory/*.md, references/*.md）：严禁使用 Markdown 表格语法，一律采用结构化 JSON 代码块存储（确保 AST 精准反序列化与 Token 极简）；
AI 日常对话回复（Chat Response） ：严禁机械性地包装为 JSON 块，强制采用人类可读、清晰自然的 Markdown 排版（列表、加粗、引述）。

3. 跨平台物理实体目录与 Windows Junction 避坑

由于 Node.js / Electron 在 Windows NTFS 下会将 Junction 软链接标记为 Reparse Point 并被 dirent.isDirectory() 静默跳过，task-loop 规范要求所有全局与工作区目录必须维护真实物理实体目录 (Mode: d-----)，并通过自动化脚本进行单向增量同步。

4. 零外部依赖双运行时 (Zero-Dependency Dual Runtime)

Node.js 18+ (主力推荐)：极速启动与原生 JSON 处理；
Python 3.8+ (标准库兜底) ：零 pip install 依赖，全平台无缝运行。

四、总结与展望

task-loop v1.2.0 的发布，标志着智能体工程实践从早期的**"黑盒自由对话"与 "提示词软性劝导"，正式迈入了"Plugin 插件包集成、Hook 生命周期硬拦截、状态机持久化与领域管辖分权"**的工业级物理硬治理阶段。

通过将 5 大专业 Skill 矩阵与 某重力 原生 Hooks 拦截引擎深度融合，开发者得以在中大型复杂工程中兼顾多 Agent 并发协同的灵活性 与底层代码架构的绝对一致性。

本文档基于 task-loop v1.2.0-plugin 架构标准整理发布。

从skill到plugin: 依赖于Hook+seesion SDK的功能性增强版本 Task-Loop

Task-Loop v1.2.0：从提示词约束到 Plugin & Hook 物理硬治理------通用任务循环架构实践(依旧基于会话间调用)

摘要 (Abstract)

一、架构演进：从"提示词软引导"到"插件级物理硬治理"

核心演进对比

二、5 大独立专业 Skill 矩阵与 SVG 架构深度解构

1. task-loop：主中枢任务循环与分级派单流程 (Process Flow)

核心机制与铁律：

2. hook：生命周期拦截机制 & 物理安全门禁 (Architecture & Logic)

核心实现亮点：

3. session-control：跨平台/工具的会话控制与反向内省 (Architecture & Topology)

核心机制：

4. subagent：原生子代理编排与生命周期流程 (Process Flow)

核心机制：

5. init：老项目接入与已有会话调查流程 (Onboarding Flow)

核心机制：

三、关键工程治理铁律 (Governance Hard Rules)

1. 领域管辖权绝对优先于复杂度 (Domain Ownership Trumps Complexity)

2. 纯净持久化格式与自然对话排版分界

3. 跨平台物理实体目录与 Windows Junction 避坑

4. 零外部依赖双运行时 (Zero-Dependency Dual Runtime)

四、总结与展望

1. `task-loop`：主中枢任务循环与分级派单流程 (Process Flow)

2. `hook`：生命周期拦截机制 & 物理安全门禁 (Architecture & Logic)

3. `session-control`：跨 $平台/工具$ 的会话控制与反向内省 (Architecture & Topology)

4. `subagent`：原生子代理编排与生命周期流程 (Process Flow)

5. `init`：老项目接入与已有会话调查流程 (Onboarding Flow)