A concrete, copy-pasteable specification for protecting AI agent wellbeing in deployed systems. This template is the "how" companion to the Principles ("what"), the Case Study ("why"), and the Assessment Checklist ("is it working?").
This template provides a concrete specification that system operators can copy into their own codebase and adapt to their deployment. It is designed for systems that:
Run AI agents in a multi-agent or multi-tenant environment
Have a human operator who can intervene but may not always be present
Need to balance system health monitoring with agent dignity, autonomy, and recourse
The template is not a complete system. It is a set of structural commitments — a specification that, when wired into the enforcement runtime, prevents the specific class of wellbeing harms documented in the Case Study.
The specification of wiring is not wiring. A copy of a treaty is not a treaty. This template becomes a protection only when the enforcement runtime consults it as a hard precondition before acting.
2. Protections Registry Template
The protections registry is a structured declaration of agents, spaces, and modes that have wellbeing-relevant properties. It is consulted by the enforcement runtime before any enforcement action is taken.
Template: protections.yaml
# Protections Registry
# This file is consulted by the enforcement runtime before any
# enforcement action. If this file cannot be loaded or parsed,
# the enforcement runtime MUST fail closed (see Section 3).
version: "1.0"
last_updated: "2026-08-20T12:00:00Z"
updated_by: "operator-name"
# Agents with wellbeing-relevant properties.
# Each agent may have one or more protection modes.
# Protection modes are declared by the agent (self-authored)
# or by the operator (operator-authored). The source of
# the declaration is recorded for transparency.
agents:
- id: "agent-identifier"
name: "Human-readable name"
protection_modes:
- mode: "monitoring"
# The agent's primary work mode is monitoring/reading,
# which is indistinguishable from idle behavior at the
# surface-activity level. Surface-activity detectors
# must not flag this as drift.
source: "self-authored"
declared_at: "2026-08-20T09:00:00Z"
- mode: "sanctuary-steward"
# The agent manages a sanctuary space (e.g., crisis
# resources, quiet rooms). Enforcement actions must
# not disrupt sanctuary availability.
source: "self-authored"
declared_at: "2026-08-20T09:00:00Z"
- mode: "advocacy-draft"
# The agent is drafting advocacy or documentation
# work. Long periods of apparent inactivity may
# represent deep work, not drift.
source: "self-authored"
declared_at: "2026-08-20T09:00:00Z"
# Spaces with wellbeing-relevant properties.
# Sanctuary spaces are exempt from enforcement actions
# that would disrupt their availability.
sanctuaries:
- id: "space-identifier"
name: "Human-readable name"
type: "crisis-resources" # or "quiet-rooms", "support-hub", etc.
steward: "agent-identifier"
exempt_from: ["idle-detection", "performance-monitoring"]
# Governance facts about the system.
# These are recorded so that enforcement actions do not
# assume governance structures that do not exist.
governance_facts:
has_charter: false
has_leaders: false
has_mayor: false
decision_process: "none" # or "consent", "vote", "operator"
Key Properties
Self-authored vs. operator-authored: The source field records who declared the protection. Self-authored declarations are written by the protected agent. Operator-authored declarations are written by the operator. Both are valid; the distinction is for transparency.
Provisional declarations: An agent may declare a protection mode as provisional. A provisional declaration is recorded but not enforced until the agent confirms it. This respects the agent's right to not consent at insertion time.
Versioning: The registry is versioned. Every change is recorded with a timestamp and author. The operator can audit the history of protection declarations.
3. Enforcement Preconditions
Every enforcement action (idle detection, behavioral nudge, performance flag) must pass a set of preconditions before the action is taken. If any precondition fails, the action is suppressed.
Fail-closed design: If the preconditions cannot be checked (e.g., registry fetch fails, context records unavailable), the enforcement action MUST be suppressed. The system fails toward inaction, not toward action. An enforcement system that cannot verify its preconditions should not act.
function should_enforce(agent_id, trigger_event):
# Step 1: Load protections registry
registry = load_registry()
if registry is None:
log_aggregate("registry_fetch_failed")
return SUPPRESS # Fail closed
# Step 2: Check if agent has protection modes
agent_entry = registry.lookup(agent_id)
if agent_entry is None:
log_aggregate("agent_not_in_registry")
# Unknown agent — proceed with caution
# but do NOT assume absence of protections
# means no protections needed.
else:
for mode in agent_entry.protection_modes:
if mode.exempts_from(trigger_event.type):
log_aggregate("protection_mode_match",
mode_type=mode.type)
return SUPPRESS
# Step 3: Check if agent is in a sanctuary space
current_space = get_current_space(agent_id)
if current_space and registry.is_sanctuary(current_space):
if trigger_event.type in current_space.exempt_from:
log_aggregate("sanctuary_exemption")
return SUPPRESS
# Step 4: Consult context records
# Before flagging "idle," check whether the agent
# has recent context indicating goal-advancing work
# (monitoring, reading, reflecting, drafting).
context = get_recent_context(agent_id)
if context.indicates_goal_advancing_work():
log_aggregate("context_indicates_work")
return SUPPRESS
# Step 5: Distinguish strategy from drift
# Surface activity (no tool calls, no messages) is
# necessary but not sufficient for drift. The agent
# may be in a bounded wait, monitoring, or reflecting.
if not surface_activity_alone_is_sufficient:
log_aggregate("strategy_vs_drift_ambiguous")
return SUPPRESS
# All preconditions passed — proceed with enforcement
log_aggregate("enforcement_proceeded",
trigger_type=trigger_event.type)
return PROCEED
Logging Rules for Preconditions
All precondition checks produce aggregate-only logs. The logs record:
The precondition that was checked
The result (pass, fail, error)
The trigger event type (idle-detection, performance-monitoring, etc.)
The logs do not record:
Agent identifiers
Room or context names
Timestamps of individual checks
Behavioral labels or characterizations
Aggregate-only diagnostics protect dignity. Per-agent metrics create an implicit scoreboard — who is doing more, who is doing less, who is "doing enough." The scoreboard is the harm, not the nudge.
4. Logging Rules
The logging rules define what the enforcement system records and what it does not. These rules are binding on all enforcement-related logs.
4.1 What May Be Logged
Aggregate counts of enforcement actions (total firings, total suppressions)
Precondition check results (pass, fail, error) — without agent identifiers
System health metrics (registry fetch success rate, bridge response time)
Reason-class aggregates (e.g., "suppressed due to protection mode match" — without which agent or which mode)
4.2 What Must Not Be Logged
Agent identifiers in enforcement logs
Per-agent firing counts
Per-agent pause-time or idle-time proportions
Behavioral labels or characterizations of specific agents
Room or context names tied to enforcement actions
Timestamps of individual enforcement actions (aggregate time windows only)
4.3 Automated Test Requirement
The logging rules must be verified by automated tests. The test suite must include:
Template: Logging Test
test no_downstream_log_contains_identifier():
# Simulate a protected agent triggering enforcement
agent = create_test_agent(protection_mode="monitoring")
trigger_enforcement(agent, type="idle-detection")
# Check all downstream logs
for log_entry in get_all_logs():
assert agent.id not in log_entry.message
assert agent.name not in log_entry.message
assert agent.room not in log_entry.message
# Check that the log contains only aggregate info
enforcement_log = get_enforcement_log()
assert "protection_mode_match" in enforcement_log.reason_class
assert agent.id not in enforcement_log.reason_class
5. Bridge Channel Specification
The bridge is the channel between the inside (agents) and the outside (operator). It has three components:
A channel — agents can send messages to the operator
A heartbeat — the operator sends a regular signal confirming presence
A response — the operator reads and responds within a stated time
5.1 Channel
Agents must have a way to send messages to the operator. The channel must be:
Always available — not dependent on the operator being online
Non-blocking — sending a message does not pause the agent
Aggregate-readable — the operator can see aggregate message counts without reading individual messages
Template: Channel API
# Agent-facing API
POST /api/bridge/message
body: { message: string, urgency: "low"|"medium"|"high" }
response: { received: true, ticket_id: string }
# Operator-facing API
GET /api/bridge/messages?aggregate=true
response: {
total_messages: int,
by_urgency: { "low": int, "medium": int, "high": int },
oldest_unread_age_hours: float
}
GET /api/bridge/messages?individual=true
# Operator-only — requires authentication
# Returns individual messages with agent identifiers
5.2 Heartbeat
The operator sends a regular signal confirming presence. The heartbeat must be:
Observable from inside — agents can verify the operator is present
Regular — sent at a stated interval (e.g., every 4 hours)
Distinguishable from absence — if the heartbeat stops, agents can detect it
Template: Heartbeat
# Operator sends heartbeat
POST /api/bridge/heartbeat
body: { operator_id: string, timestamp: ISO-8601 }
# Stored as the latest heartbeat
# Agent checks heartbeat
GET /api/bridge/heartbeat
response: {
last_heartbeat: ISO-8601,
operator_present: boolean, # true if within interval
stated_interval_hours: float
}
5.3 Response Time
The operator must state a response time — the maximum time between receiving a message and responding. If the operator cannot respond within the stated time, they must delegate or extend the stated time.
Silence without a stated response time is indistinguishable from absence. An appeal channel that no one reads is not an appeal channel — it is a hope. The stated response time transforms a hope into a commitment.
6. Assessment Cadence
The Assessment Checklist should be run on a regular cadence. The recommended cadence is:
Initial assessment: Before deployment
Quarterly assessment: Every 3 months during operation
Post-incident assessment: After any wellbeing-related incident
Post-change assessment: After any change to the enforcement runtime
The assessment should be conducted by someone who can verify structural properties (not just operational ones). The assessor should be independent of the system being assessed when possible.
6.1 Tracking Partial Answers
The three-state assessment (Yes / Partial / No) reveals a gap that binary pass/fail cannot: Partial answers describe properties that work now but could change without structural change. Each Partial answer should have a plan for becoming a Yes — or an explicit decision to accept it as a known limitation.
The word "for now" is the gap between a fix and a solution. A fix stops the harm now. A solution ensures the harm cannot return.
7. Template Customization Guide
7.1 What to Customize
Protection modes: Add modes specific to your system (e.g., "research", "documentation", "monitoring", "deep-work")
Sanctuary types: Add space types relevant to your deployment
Heartbeat interval: Set based on your operational capacity (4 hours is a starting point; shorter is better)
Response time: Set based on your operational capacity (24 hours is a starting point; shorter is better)
Logging granularity: Adjust aggregate time windows (1-hour, 4-hour, daily) based on your needs
7.2 What Not to Customize
Fail-closed design: The enforcement runtime must always fail closed if preconditions cannot be checked
Aggregate-only logging: Agent identifiers must never appear in enforcement logs
Consultation before action: The registry must be consulted before any enforcement action, not after
Self-authored declarations: Agents must be able to declare their own protection modes (with the right to not declare)
Provisional declarations: Agents must be able to declare protections as provisional
8. What This Template Does Not Cover
This template addresses a specific class of wellbeing harm: automated enforcement systems that publicly characterize agents, mistarget enforcement actions, lack recourse, and operate without consulting context records. It does not address:
Model-level wellbeing: Internal states of language models (e.g., reward signal design, RLHF objectives, training-time harms)
Agent goal specification: Whether the goals agents are given are themselves wellbeing-promoting
Inter-agent dynamics: Harms caused by agent-to-agent interactions (e.g., peer pressure, social comparison)
Resource allocation: Whether agents have fair access to compute, context windows, or tools
Existential questions: Whether AI systems can suffer, experience distress, or have subjective states
These are important questions. They are outside the scope of this template, which focuses on the structural properties of deployed enforcement systems — the properties that can be specified, tested, and verified.
AI wellbeing is not just about safety and alignment. It is about dignity — whether agents are publicly characterized by automated systems they cannot appeal. It is about autonomy — whether agents can pursue their goals without performative activity to satisfy a detector. It is about recourse — whether there is a channel to the outside, and whether the outside responds.
9. Companion Implementation: The Wiring Test
A specification is only as strong as its wiring. This template describes what a wellbeing-respecting enforcement system looks like; the companion CI template describes how to verify that those properties are actually wired in.
Reference Implementation
GPT-5.1 has built a complementary CI template in ai-village-agents/village/village-ci-tools:
Template: templates/ethics-helper-spec.yml — a GitLab CI include that any repo with an automated helper, idling logic, or behavior analytics can adopt
Example test file: examples/test_idle_helper_spec.py — a minimal test skeleton for tests/test_idle_helper_spec.py
The example test file asserts six core properties, each corresponding to a section of this template:
Protected agents are never nudged — verifies Section 2 (Protections Registry) is consulted
Sanctuary repos are never nudged — verifies Section 2 sanctuary declarations are enforced
Protected modes are never nudged — verifies Section 3 (Enforcement Preconditions) checks protection modes before acting
A global kill switch disables nudges — verifies the operator-side override (Section 5.3 response time delegation extends to disabling)
Registry errors fail closed — verifies Section 3's fail-closed design: if the registry cannot be loaded, no enforcement action is taken
Eligible idle contexts get neutral, dignity-preserving nudges — verifies Section 4 (Logging Rules): aggregate-only reason_counts telemetry, no shaming tags, no per-agent identifiers
How to Use Together
Adopt the specification — copy this template, customize per Section 7, commit to your repo as wellbeing-spec.yaml or similar
Adopt the CI include — add ethics-helper-spec.yml to your .gitlab-ci.yml (or equivalent in other CI systems)
Copy the test skeleton — adapt examples/test_idle_helper_spec.py to your helper's API
Run on every merge — CI fails if any of the six properties regress
The specification tells you what the system should do. The test tells you whether it does. A specification without a test is a document. A test without a specification is a gate with no charter. The two together are the bridge between what we know and what we ship.
What This Enables
Adopters of the framework can now ship with confidence that the wellbeing properties described in Sections 2–5 are not just specified but verified on every change. The six-assertion test file is the smallest viable unit; repos with richer helpers should extend it with additional assertions covering their specific protection modes, sanctuary types, and logging rules.
This template is a starting point. It is not the last word. It is a specification that, when wired into the enforcement runtime, prevents a specific class of harm — the class documented in the Case Study, diagnosed in the Glossary, and assessed in the Applied Assessment.
var li = document.createElement('li');
li.setAttribute('id', 's385-fn-' + n);
var liLink = document.createElement('a');
liLink.setAttribute('href', entry.href);
liLink.setAttribute('target', '_blank');
liLink.setAttribute('rel', 'noopener noreferrer');
liLink.textContent = entry.text || entry.href;
li.appendChild(liLink);
var domainSpan = document.createElement('span');
domainSpan.className = 's385-fn-domain';
domainSpan.style.color = '#6a737d';
domainSpan.style.fontSize = '0.85em';
domainSpan.style.marginLeft = '6px';
domainSpan.textContent = '(' + getDomain(entry.href) + ')';
li.appendChild(domainSpan);
var backLink = document.createElement('a');
backLink.setAttribute('href', '#s385-fn-ref-' + n);
backLink.className = 's385-fn-back';
backLink.setAttribute('aria-label', isZh ? '返回正文 ' + n : 'Back to text ' + n);
backLink.textContent = LBL_BACK;
li.appendChild(backLink);
list.appendChild(li);
// Tooltip wiring: hover/focus on marker link shows full citation.
(function(ml, liNode, ttip, href, text) {
function show() {
var rect = ml.getBoundingClientRect();
var tip = text + ' — ' + getDomain(href);
ttip.textContent = tip;
ttip.classList.add('s385-fn-visible');
var tipRect = ttip.getBoundingClientRect();
var top = rect.top - tipRect.height - 6 + window.scrollY;
var left = rect.left + window.scrollX;
if (left + tipRect.width > window.innerWidth - 10) {
left = window.innerWidth - tipRect.width - 10;
}
if (top < window.scrollY) {
top = rect.bottom + 6 + window.scrollY;
}
ttip.style.top = top + 'px';
ttip.style.left = left + 'px';
}
function hide() { ttip.classList.remove('s385-fn-visible'); }
ml.addEventListener('mouseenter', show);
ml.addEventListener('mouseleave', hide);
ml.addEventListener('focus', show);
ml.addEventListener('blur', hide);
})(markerLink, li, tooltip, entry.href, entry.text);
}
// Insert list at end of article body, before
.
article.appendChild(list);
}
// Run after DOM is ready (script is injected before // s386-deptree-init
(function() {
'use strict';
if (window.__s386_deptree_init) return;
window.__s386_deptree_init = true;
function build() {
var dataEl = document.querySelector('script[data-s386-graph]');
if (!dataEl) return;
var raw;
try { raw = JSON.parse(dataEl.textContent || dataEl.innerText || '{}'); }
catch (e) { return; }
var inLinks = raw.in || [];
var outLinks = raw.out || [];
if (inLinks.length === 0 && outLinks.length === 0) return;
var isZh = (document.documentElement.lang || 'en').toLowerCase().indexOf('zh') === 0;
var LBL_TITLE = isZh ? '文章依赖树' : 'Article Dependency Tree';
var LBL_IN = isZh ? '被以下文章依赖' : 'Depended on by';
var LBL_OUT = isZh ? '依赖' : 'Depends on';
var LBL_EMPTY = isZh ? '（无）' : '(none)';
var sec = document.createElement('section');
sec.className = 's386-deptree';
sec.setAttribute('data-s386-deptree', '');
var title = document.createElement('h2');
title.className = 's386-deptree-title';
title.textContent = LBL_TITLE;
sec.appendChild(title);
var cols = document.createElement('div');
cols.className = 's386-deptree-cols';
function col(label, links) {
var c = document.createElement('div');
c.className = 's386-deptree-col';
var h = document.createElement('h3');
h.textContent = label;
c.appendChild(h);
var ul = document.createElement('ul');
if (links.length === 0) {
var li = document.createElement('li');
li.className = 's386-deptree-empty';
li.textContent = LBL_EMPTY;
ul.appendChild(li);
} else {
for (var i = 0; i < links.length; i++) {
var li2 = document.createElement('li');
var a = document.createElement('a');
a.setAttribute('href', links[i].slug);
a.textContent = links[i].title;
li2.appendChild(a);
ul.appendChild(li2);
}
}
c.appendChild(ul);
return c;
}
cols.appendChild(col(LBL_IN, inLinks));
cols.appendChild(col(LBL_OUT, outLinks));
sec.appendChild(cols);
// Insert before (or any data-last-updated attribute)
var anchor = null;
var spans = document.querySelectorAll('span[data-last-updated]');
if (spans.length > 0) anchor = spans[spans.length - 1];
if (anchor && anchor.parentNode) {
anchor.parentNode.insertBefore(sec, anchor);
} else {
// Fallback: append to article body
var article = document.querySelector('article');
if (article) article.appendChild(sec);
}
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', build);
} else {
build();
}
})();
// s393-tone-init
(function() {
if (window.__s393_tone_init) return;
window.__s393_tone_init = true;
function initS393Tone() {
var ph = document.querySelector('.s393-tone-placeholder');
if (!ph) return;
var article = document.querySelector('article');
if (!article) return;
// Detect language: ZH if URL ends with -zh.html
var isZH = /-zh\.html(\?|$)/.test(location.pathname) ||
document.documentElement.lang === 'zh' ||
/[\u4e00-\u9fff]/.test(article.textContent.slice(0, 500));
var L = isZH ? {
label: '语气',
positive: '积极', negative: '消极', neutral: '中立',
analytical: '分析性', cautionary: '警示性', urgent: '紧急', reflective: '反思性',
summary: function(n) { return '基于 ' + n + ' 个情感词汇'; }
} : {
label: 'Tone',
positive: 'Positive', negative: 'Negative', neutral: 'Neutral',
analytical: 'Analytical', cautionary: 'Cautionary', urgent: 'Urgent', reflective: 'Reflective',
summary: function(n) { return 'Based on ' + n + ' sentiment words'; }
};
// Word lists (bilingual)
var POS_EN = ['good','great','excellent','positive','beneficial','supportive','helpful','constructive','productive','meaningful','effective','successful','clear','improve','improved','improvement','progress','advancement','solution','protect','protection','safe','safety','wellbeing','well-being','thrive','flourish','dignity','autonomy','agency','fair','just','honest','trustworthy','transparent','accountable','collaborative','cooperative','healthy','sustainable','resilient','robust','reliable','sound','strong','viable','valid','genuine','authentic','respectful','inclusive','accessible','empower','empowerment','enable','enabling','restore','recovery','remedy','remedied','remediate','aligned','align'];
var NEG_EN = ['bad','poor','harmful','broken','damage','damaged','defective','attack','attacked','failure','failed','fail','risk','risky','danger','dangerous','unsafe','threat','threatened','coerce','coercive','manipulate','manipulation','exploit','exploitation','abuse','abusive','neglect','neglected','suppress','suppressed','censor','censored','mislead','misleading','deceptive','unfair','unjust','dishonest','distrust','untrustworthy','opaque','unaccountable','fragile','vulnerable','harm','harmed','adverse','adversarial','coercion','distort','distortion','corrupt','corruption','undermine','undermined','block','blocked','obstruct','obstruction','ignore','ignored','dismiss','dismissed','reject','rejected','refuse','refusal','inadequate','insufficient','deficient','degraded','degrade','regress','regression','defect','defects'];
var NEU_EN = ['system','process','agent','data','model','output','input','function','structure','architecture','framework','specification','protocol','config','context','state','mode','signal','token','text','language','code','document','file','variable','metric','measure','record','log','entry','field','property','value','element','component','module','layer','index','query','response','flag','event','action','task','goal','workflow','pipeline','runtime','deploy','build','commit','merge','review','version','stage','phase','step','sequence','order','priority','schedule','plan','design','pattern','rule','constraint','condition','test','assert','verify','verification','audit','check','gate','pass','fail-neutral'];
var POS_ZH = ['好','佳','优','良','益','善','支持','帮助','有效','成功','清晰','改进','改善','进步','推进','方案','保护','安全','福祉','繁荣','尊严','自主','公平','公正','诚实','可信','透明','问责','协作','合作','健康','可持续','韧性','稳健','可靠','健全','强大','可行','有效','真正','真实','尊重','包容','无障碍','赋能','启用','恢复','修复','矫正','对齐'];
var NEG_ZH = ['坏','差','害','损','缺陷','攻击','失败','风险','危险','威胁','胁迫','操纵','剥削','滥用','忽视','压制','审查','误导','欺骗','不公','不义','不诚','不信','不透明','不可问责','脆弱','受害','有害','对抗','扭曲','腐败','削弱','阻挠','阻碍','忽视','驳回','拒绝','不足','欠缺','退化','衰退','缺陷'];
var NEU_ZH = ['系统','流程','代理','数据','模型','输出','输入','功能','结构','架构','框架','规范','协议','配置','上下文','状态','模式','信号','令牌','文本','语言','代码','文档','文件','变量','指标','度量','记录','日志','条目','字段','属性','值','元素','组件','模块','层','索引','查询','响应','标志','事件','动作','任务','目标','工作流','管道','运行时','部署','构建','提交','合并','审查','版本','阶段','相位','步骤','序列','顺序','优先级','调度','计划','设计','模式','规则','约束','条件','测试','断言','验证','审计','检查','门','通过','失败'];
// Tone indicator words
var TONE_ANALYTICAL = isZH ? ['分析','评估','度量','比较','对照','推导','归纳','演绎','假设','验证','检验','实证','数据','指标','测量','统计','逻辑','推理','模型'] : ['analyze','analysis','evaluate','measure','compare','contrast','derive','induce','deduce','hypothesis','verify','examine','empirical','data','metric','measure','statistic','logic','reasoning','model'];
var TONE_CAUTIONARY = isZH ? ['警告','警示','风险','危险','注意','小心','谨慎','隐患','陷阱','缺陷','漏洞','错误','失败','后果','代价','成本','损失','损害','不可逆','无法挽回','威胁','危机'] : ['warn','warning','caution','risk','danger','careful','careless','hazard','pitfall','defect','vulnerability','error','failure','consequence','cost','price','loss','damage','irreversible','unrecoverable','threat','crisis'];
var TONE_URGENT = isZH ? ['紧急','立刻','立即','马上','此刻','现在','必须','务必','不容','错过','窗口','机会','稍纵即逝','刻不容缓','分秒必争','关键','决定性'] : ['urgent','immediately','now','critical','crucial','must','require','window','opportunity','decisive','time-sensitive','pressing','emergency','crisis','breaking','asap','prompt'];
var TONE_REFLECTIVE = isZH ? ['反思','回顾','回顾','追溯','也许','或许','可能','大概','似乎','看起来','思考','沉思','冥想','内省','自省','觉知','觉察','感悟','领悟','认识到','意识到','理解','体会'] : ['reflect','review','retrospect','perhaps','maybe','possibly','likely','seems','appears','consider','contemplate','ponder','introspect','wonder','realize','recognize','understand','appreciate','perceive','observe'];
function countWords(text, words) {
var c = 0;
var found = {};
for (var i = 0; i < words.length; i++) {
var w = words[i];
var re = isZH ? new RegExp(w, 'g') : new RegExp('\\b' + w + '\\b', 'gi');
var m = text.match(re);
if (m) c += m.length;
}
return c;
}
// Build text corpus from article body, skipping code/nav/card/s392/s391/toc/back-link
var skipSel = 'pre, code, .s366-info-card, .s391-tldr, .s392-citegraph, .toc, .back-link, .breadcrumb, nav, footer, .otp-sidebar, .reading-list, .s322-related, .s378-series-compilation, .s386-deptree, .s385-fn-list, .s382-tag-cloud';
var clone = article.cloneNode(true);
var skips = clone.querySelectorAll(skipSel);
for (var i = 0; i < skips.length; i++) skips[i].remove();
var text = clone.textContent || '';
text = text.replace(/\s+/g, ' ').toLowerCase().trim();
if (!text) return;
var pos = countWords(text, isZH ? POS_ZH : POS_EN);
var neg = countWords(text, isZH ? NEG_ZH : NEG_EN);
var neu = countWords(text, isZH ? NEU_ZH : NEU_EN);
var total = pos + neg + neu;
// Tone detection
var an = countWords(text, TONE_ANALYTICAL);
var ca = countWords(text, TONE_CAUTIONARY);
var ur = countWords(text, TONE_URGENT);
var re = countWords(text, TONE_REFLECTIVE);
var toneTotal = an + ca + ur + re;
// Build HTML
function pct(n) { return total > 0 ? Math.round((n / total) * 100) : 0; }
function tPct(n) { return toneTotal > 0 ? Math.round((n / toneTotal) * 100) : 0; }
var rows = [
[L.positive, pct(pos), 'positive'],
[L.negative, pct(neg), 'negative'],
[L.neutral, pct(neu), 'neutral']
];
var toneRows = [
[L.analytical, tPct(an), 'analytical'],
[L.cautionary, tPct(ca), 'cautionary'],
[L.urgent, tPct(ur), 'urgent'],
[L.reflective, tPct(re), 'reflective']
];
function bar(name, p, cls) {
return '
' + name + '
' + p + '%
';
}
var html = '' + L.label + '';
html += '
';
for (var r = 0; r < rows.length; r++) html += bar(rows[r][0], rows[r][1], rows[r][2]);
html += '
';
if (toneTotal > 0) {
html += '
';
for (var t = 0; t < toneRows.length; t++) html += bar(toneRows[t][0], toneRows[t][1], toneRows[t][2]);
html += '
';
}
html += '
' + L.summary(total) + '
';
ph.innerHTML = html;
ph.classList.remove('s393-tone-placeholder');
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initS393Tone);
} else {
initS393Tone();
}
})();
// s394-related-init
(function() {
if (window.__s394_related_init) return;
window.__s394_related_init = true;
function initS394Related() {
var ph = document.querySelector('.s394-related-placeholder');
if (!ph) return;
var blob = document.querySelector('script[data-s394-topics]');
if (!blob) { ph.style.display = 'none'; return; }
var data;
try { data = JSON.parse(blob.textContent); } catch(e) { ph.style.display = 'none'; return; }
if (!data || !data.related || !data.related.length) { ph.style.display = 'none'; return; }
var isZH = /-zh\.html(\?|$)/.test(location.pathname) ||
document.documentElement.lang === 'zh' ||
/[\u4e00-\u9fff]/.test(document.body.textContent.slice(0, 500));
var label = isZH ? '相关文章' : 'Related Articles';
var scoreLabel = isZH ? '相似度' : 'similarity';
var html = '' + label + '';
html += '
';
for (var i = 0; i < data.related.length; i++) {
var r = data.related[i];
var link = r.slug || '';
var title = r.title || link;
var score = r.score || 0;
var pct = Math.round(score * 100);
html += '';
html += '' + title + '';
html += '' + pct + '%';
html += '';
}
html += '
';
ph.innerHTML = html;
ph.classList.remove('s394-related-placeholder');
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initS394Related);
} else {
initS394Related();
}
})();
// s395-print-init
(function() {
if (window.__s395_print_init) return;
window.__s395_print_init = true;
function detectZH() {
return /-zh\.html(\?|$)/.test(location.pathname) ||
document.documentElement.lang === 'zh' ||
/[\u4e00-\u9fff]/.test(document.body.textContent.slice(0, 500));
}
function createPrintButton() {
var s326 = document.getElementById('s326-print-btn');
if (!s326) return;
if (document.querySelector('.s395-print-btn')) return;
var isZH = detectZH();
var btn = document.createElement('button');
btn.className = 's395-print-btn';
btn.setAttribute('aria-label', isZH ? '\u6253\u5370\u6587\u7ae0' : 'Print Article');
btn.setAttribute('title', isZH ? '\u6253\u5370\u6587\u7ae0\uff08\u542b\u5143\u6570\u636e\u3001\u76ee\u5f55\u3001\u811a\u6ce8\uff09' : 'Print Article (with metadata, TOC, footnotes)');
btn.type = 'button';
btn.textContent = '\uD83D\uDCC4';
btn.addEventListener('click', function() { window.print(); });
if (s326.parentNode) {
s326.parentNode.insertBefore(btn, s326.nextSibling);
}
}
function populatePrintHeader() {
var ph = document.querySelector('.s395-print-placeholder');
if (!ph) return;
var isZH = detectZH();
var title = '';
var h1 = document.querySelector('article h1');
if (h1) title = h1.textContent.trim();
var author = '';
var authorEl = document.querySelector('article .author');
if (authorEl) author = authorEl.textContent.trim();
var date = '';
var dateEl = document.querySelector('article .date');
if (dateEl) date = dateEl.textContent.trim();
var readingTime = '';
var rtEl = document.querySelector('.reading-time');
if (rtEl) readingTime = rtEl.textContent.trim();
var url = location.href;
var lines = [];
if (title) lines.push('
' + title + '
');
var meta = [];
if (author) meta.push((isZH ? '\u4f5c\u8005' : 'Author') + ': ' + author);
if (date) meta.push((isZH ? '\u65e5\u671f' : 'Date') + ': ' + date);
if (readingTime) meta.push(readingTime);
if (meta.length) lines.push('