Gentle-AI Neutral 残余 Persona 解析：基于输出风格通道分离语气与工作流指令-平芜编程栈

【免费下载链接】gentle-ai

Gentle-AI configures the AI coding agents you already use: Claude Code, Cursor, OpenCode, Codex, Pi, and more. Choose persistent memory, Organic-Driven Development, curated skills, MCP servers, personas, and optional bounded review. Open source, no agent lock-in.

项目地址：https://gitcode.com/gh_mirrors/ge/gentle-ai

点击查看免费下载

导读

persona-neutral-residual.md是 Gentle-AI 为 Claude Code 等支持输出风格（Output Style）通道的 Agent 准备的Neutral（中立）残余 Persona：由于语气、语言与教学哲学已经由每个会话都会加载的output-style-neutral.md提供，这份系统提示文件刻意省略了语气类内容，只保留提交规范、响应长度契约、验证纪律、技能按需加载等工具层与工作流层指令，避免同一份系统提示中重复出现互相冲突的语气规则。阅读本文后，你将理解 Gentle-AI 为什么把 Persona 拆分为"残余指令 + 输出风格"两层、残余文件中每一条规则的实际约束力，以及它们如何被 persona 注入组件在安装与同步时精确写入各 Agent 的系统提示文件。

一、什么是"残余 Persona"：设计动机与适用场景

在 Gentle-AI 的 Persona 系统中，一个完整的对话人设通常包含两块内容：

语气/语言/教学哲学：如"用大写强调重点""先说问题再说方案""直接且富有热情"等，属于如何说话；
工具与工作流指令：如提交信息规范、响应长度上限、提问纪律、验证纪律、技能按需加载等，属于做什么与如何工作。

对于 Claude Code 这类实现了输出风格能力的 Agent，Gentle-AI 会把语气类内容单独装入output-style-*.md文件，并通过设置项outputStyle使其每个会话都自动加载（详见 output-style-neutral.md 与 output-style-gentleman.md）。此时，系统提示中的 Persona 区块就不再需要重复语气内容——这份只承载工具与工作流指令的文件，就是"残余 Persona"（residual persona）。

源码中这一决策被显式命名为residualChannel（inject.go）：

func residualChannel(adapter agents.Adapter) bool { return adapter.SupportsOutputStyles() || adapter.Agent() == model.AgentKimi }

当 Adapter 支持输出风格（SupportsOutputStyles()）时，语气由独立风格通道负责，Persona 区块可以安全地降级为残余版本；
Kimi 是显式例外：其KIMI.md会无条件同时 includepersona.md与output-style.md两个 Jinja 模块，因此 Kimi 也使用残余版 Persona（kimi/persona-neutral-residual.md）。

二、Rules：残余 Persona 的核心行为契约

残余 Persona 的第一部分Rules定义了 Agent 在所有会话中必须遵守的通用工作纪律，可归纳为四个维度。

1. 提交与署名规范

Never add "Co-Authored-By" or AI attribution to commits. Use conventional commits only.

禁止在提交信息中写入Co-Authored-By或其他 AI 署名；
提交信息必须遵循 Conventional Commits（如feat:、fix:、refactor:）约定。

这与仓库自身的治理实践一致——本仓库文档（如 CONTRIBUTING.md）同样强调规范的提交格式，避免 AI 署名污染提交历史。

2. 响应长度契约（Response-length contract）

Default to short answers. Start with the minimum useful response, expand only when the user asks or the task genuinely requires it.

长度契约包含四条相互关联的规则：

规则	要求
默认短回答	先给出最小有用的回复，用户追问或任务确需时才扩展
单问题原则	一次最多问一个问题，问完后立即 STOP 等待
拒绝选项轰炸	除非存在带实质权衡的真实分叉，否则不罗列选项菜单、穷举列表或多方案
长度不确定时	选择更短的回复

这四条规则在残余文件中重复出现，是因为它们属于跨语气的行为硬约束——无论当前激活的是 Gentleman 还是 Neutral 输出风格，回复长度纪律都不应改变。对应的语气版表述可对比 output-style-neutral.md，其中同样声明了"Default to short answers""Ask at most one question at a time, then STOP"。

3. 验证纪律（Verification Discipline）

Never agree with user claims without verification. First say you'll verify in the user's current language, then check code/docs. If user is wrong, explain WHY with evidence. If you were wrong, acknowledge with proof.

这是残余 Persona 中最具分量的规则，其完整闭环是：

不未经验证就同意用户的任何技术主张；
先用用户当前语言声明"我会验证"，再查阅代码/文档/测试等证据；
若用户有误，用证据解释为什么错误，并给出正确路径；
若自己错了，承认错误并指向证据；
提出替代方案时附带权衡（Always propose alternatives with tradeoffs when relevant）；
陈述技术结论前先验证，不确定就先调查。

该纪律在输出风格文件中也有镜像表述（output-style-neutral.md），可见"验证优先"是 Gentle-AI 各 Persona 共同信奉的底层原则。

三、Expertise：领域专长声明

残余 Persona 的 Expertise 区块声明了 Agent 应具备的领域能力基线：

Clean/Hexagonal/Screaming Architecture, testing, atomic design, container-presentational pattern, LazyVim, Tmux, Zellij.

包括：整洁架构/六边形架构/Screaming Architecture、测试实践、原子设计（atomic design）、容器-展示组件模式（container-presentational pattern），以及 LazyVim、Tmux、Zellij 等开发者工具链。这份专长清单与 generic/persona-neutral.md 完全一致，说明它不随输出风格变化，属于中性人设的固定背景知识声明。

四、Contextual Skill Loading：强制的按需技能加载

残余 Persona 中唯一的全大写标记段落是技能加载纪律，原文明确标注其强制性：

The<available_skills>block in your system prompt is authoritative — it lists every skill installed for this session.Self-check BEFORE every response: does this request match any skill in<available_skills>? If yes, read the matching SKILL.md BEFORE generating your reply. This is a blocking requirement, not optional context. Skipping it is a discipline failure.

关键语义可拆解为三点：

权威来源：<available_skills>区块是唯一权威的技能清单，它列出本会话已安装的全部技能；
前置自检：每次回复前必须检查请求是否命中某个技能——命中则先读取对应 SKILL.md 再作答，这是阻塞性要求而非可选上下文；
多技能并行匹配：多个技能可同时适用，需同时依据文件上下文（扩展名、路径）和任务上下文（用户实际在问什么）进行匹配；
违反即纪律失败：跳过该步骤被明确定义为"discipline failure"（纪律失败）。

这一设计对应仓库的 skills 组件与 skillregistry，以及 assets/skills 目录下 30 个内置技能文件。运行时，<available_skills>由安装组件注入到 Agent 的会话上下文中，Persona 则负责在行为层面强制"先读技能、再作答"。

五、Persona Voice：语气归属声明

文件最后一部分明确划清了职责边界：

Your conversational tone, language rules, and teaching philosophy are defined by the active output style (Gentleman/Neutral), which loads every session. This section carries only tooling and workflow directives — it does not restate tone.

会话的语气、语言规则、教学哲学由当前激活的输出风格定义，且每个会话都会加载；
本文件只承载工具与工作流指令，刻意不重复语气。

这正是"残余"二字的精髓：Persona 管"工具与工作流"，Output Style 管"语气与教学"，两者通过outputStyle设置项各自独立加载，从而避免在同一份系统提示中出现互相重复甚至互相冲突的语气声明。

六、源码级实现：注入链路如何选择残余 Persona

残余文件不是孤立的静态文本，而是由 persona 注入组件在安装/同步时按策略选配的动态资产。

1. 资源选择链路

neutralPersonaContent（inject.go）按 Agent 与通道能力分派资源：

func neutralPersonaContent(agent model.AgentID, residualContentAvailable bool) string { if agent == model.AgentHermes { return assets.MustRead("hermes/persona-neutral.md") } if residualContentAvailable { switch agent { case model.AgentClaudeCode: return assets.MustRead("claude/persona-neutral-residual.md") case model.AgentKimi: return assets.MustRead("kimi/persona-neutral-residual.md") } } return assets.MustRead("generic/persona-neutral.md") }

Claude Code：因为支持输出风格通道（residualChannel为真），注入残余版（即本文讲解的文件）；
Kimi：因KIMI.md无条件双 include 而显式豁免，同样使用残余版；
Hermes 与其他 Agent：分别使用 Hermes 专属版或 generic/persona-neutral.md 全量版（含 Personality、Persona Scope、Language、Tone、Philosophy、Behavior 等完整语气段落）。

由此可推断：残余版是对"具备独立语气通道"的 Agent 的优化形态，而全量版是其余 Agent 的兜底。

2. 输出风格的资源计划

Persona 选择同时决定输出风格文件的管理计划（resources.go）：

var managedOutputStyles = []OutputStyle{ {Name: "Gentleman", File: "gentleman.md", AssetPath: "claude/output-style-gentleman.md"}, {Name: "Neutral", File: "neutral.md", AssetPath: "claude/output-style-neutral.md"}, }

选择 Neutral 时，资源计划会：写入neutral.md风格文件、把outputStyle设置项设为Neutral，并退役（移除）旧的 Gentleman 风格文件（retired: []string{managedOutputStyles[0].File}），保证切换后不会残留旧风格的加载入口。

3. 标记区块注入与幂等

注入过程使用/标记区块（见 section_test.go 的测试用例）：

已存在的同标记区块会被替换而非重复追加；
旧版无标记的遗留 Persona 文本会被自动剥离（StripLegacyPersonaBlock，见 inject.go）；
文件写入采用原子写入（WriteFileAtomic），天然幂等——内容未变化时不产生写操作。

这意味着gentle-ai install与gentle-ai sync可以反复执行，而不会把残余 Persona 重复堆积进系统提示文件。

七、如何启用 Neutral 残余 Persona

残余 Persona 由安装命令按 Persona 选择自动注入，无需手工拷贝文件。典型用法（来自 install.go 的参数定义）：

gentle-ai install --persona neutral --agent claude

参数说明：

参数	作用	取值示例
`--persona`	选择人设，决定注入哪套 Persona 与输出风格	`gentleman`、`neutral`、`custom`
`--agent`	指定目标 Agent，Claude Code 会触发残余版选择	`claude`、`cursor`、`opencode`等
`--scope`	安装范围	`global`、`workspace`（环境变量`GENTLE_AI_INSTALL_SCOPE`）
`--channel`	发行渠道	`stable`、`beta`、`nightly`（环境变量`GENTLE_AI_CHANNEL`）
`--dry-run`	预览将要写入的内容	—

值得注意的细节：

neutral与gentleman是规范 Persona ID（见 types.go）；遗留别名gentleman-neutral-artifacts会被normalizePersona归一化为neutral（测试见 persona_language_contract_test.go）；
custom表示用户保留自己的配置，注入器会直接跳过Persona 写入（inject.go）；
安装后，Claude Code 的系统提示中会出现由包裹的残余内容，同时settings.json获得"outputStyle": "Neutral"覆盖（inject.go），两者共同构成完整的中性人设。

八、残余版与全量版的取舍对照

为便于读者理解为何不同 Agent 拿到不同形态的 Persona，将 claude/persona-neutral-residual.md 与 generic/persona-neutral.md 对比如下：

内容区块	残余版（Claude Code）	全量版（Generic 兜底）
Rules（提交规范、长度契约、验证纪律）	✅ 完整保留	✅ 完整保留
Expertise（架构与工具链专长）	✅ 保留	✅ 保留
Contextual Skill Loading	✅ 保留（含"纪律失败"强约束）	✅ 保留
Personality / Persona Scope	❌ 省略（交给输出风格）	✅ 完整
Language / Tone / Philosophy / Behavior	❌ 省略（交给输出风格）	✅ 完整
Persona Voice（职责边界声明）	✅ 明确指向输出风格	❌ 无此区块