OpenProgram/docs/reference/design/runtime/agent-capability-configuration-ui.html at main · Fzkuji/OpenProgram · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>Agent 能力配置 — OpenProgram</title>
<style>
  :root{color-scheme:dark;--bg:#111216;--surface:#17191e;--surface2:#1d2026;--surface3:#242830;--line:#303540;--line2:#454c59;--text:#eceef2;--muted:#a0a6b1;--quiet:#747b87;--cyan:#63ccd8;--blue:#82aef8;--green:#78d29e;--orange:#eca06d;--red:#ee7b7b;--purple:#b39af2;--mono:ui-monospace,"SFMono-Regular",Menlo,monospace;--sans:-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC",sans-serif}*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--text);font:15px/1.65 var(--sans)}button,input,select{font:inherit}button{cursor:pointer}a{color:var(--blue)}code{padding:1px 5px;border-radius:4px;background:#24272e;color:#dce0e7;font:12px var(--mono)}.page{width:min(1180px,calc(100% - 32px));margin:auto;padding:28px 0 72px}.doc-nav{display:flex;flex-wrap:wrap;gap:6px;margin-bottom:22px}.doc-nav a{padding:5px 9px;border:1px solid var(--line);border-radius:7px;color:#adb3bd;text-decoration:none;font-size:12px}.doc-nav a[aria-current="page"]{border-color:#39727c;background:#162126;color:#8fe0e9}header{padding-bottom:23px;border-bottom:1px solid var(--line)}.eyebrow{color:var(--cyan);font:11px var(--mono);letter-spacing:.08em;text-transform:uppercase}h1{margin:8px 0 10px;font-size:clamp(28px,4vw,40px);line-height:1.15}h2{margin:0 0 14px;font-size:23px}h3{margin:0;font-size:16px}h4{margin:0;font-size:12px}.lead{max-width:930px;margin:0;color:#c7cbd3;font-size:16px}section{padding:29px 0;border-bottom:1px solid var(--line)}p{margin:9px 0}.callout{margin:14px 0;padding:12px 14px;border-left:3px solid var(--cyan);background:#162126;color:#c9dadd}.warning{border-left-color:var(--orange);background:#241d18;color:#d9cabf}table{width:100%;margin:14px 0;border-collapse:collapse;font-size:13px}th,td{padding:10px 11px;border:1px solid var(--line);text-align:left;vertical-align:top}th{background:var(--surface2)}td{color:#bec3cc}.prototype{overflow:hidden;margin:17px 0;border:1px solid var(--line);border-radius:12px;background:#0f1013}.proto-head{display:flex;align-items:center;gap:10px;padding:12px 14px;border-bottom:1px solid var(--line);background:#15171b}.avatar{display:grid;place-items:center;width:34px;height:34px;border:1px solid #3d5660;border-radius:9px;background:#172227;color:var(--cyan);font:12px var(--mono)}.proto-head p{margin:1px 0 0;color:var(--muted);font-size:9px}.saved{margin-left:auto;color:var(--green);font:9px var(--mono)}.proto-tabs{display:flex;gap:3px;padding:0 14px;border-bottom:1px solid var(--line);overflow:auto}.proto-tab{flex:none;padding:10px;border:0;border-bottom:2px solid transparent;background:transparent;color:#818895;font-size:10px}.proto-tab[aria-selected="true"]{border-bottom-color:var(--cyan);color:#edf0f3}.proto-body{padding:16px}.proto-panel[hidden]{display:none}.panel-head{display:flex;align-items:flex-start;gap:12px;margin-bottom:13px}.panel-head p{margin:2px 0 0;color:var(--muted);font-size:10px}.entity-link{margin-left:auto;padding:5px 8px;border:1px solid var(--line);border-radius:6px;color:#9ebee9;text-decoration:none;font-size:9px}.mode-grid{display:grid;grid-template-columns:repeat(3,1fr);gap:8px}.mode{position:relative;padding:11px 32px 11px 11px;border:1px solid var(--line);border-radius:8px;background:#17191e}.mode:has(input:checked){border-color:#39727c;background:#162126}.mode input{position:absolute;top:12px;right:11px;accent-color:var(--cyan)}.mode strong{display:block;font-size:10px}.mode p{margin:3px 0 0;color:#858c97;font-size:8px}.access{display:grid;grid-template-columns:minmax(0,1fr) auto;gap:14px;align-items:center;margin-top:11px;padding:13px;border:1px solid var(--line);border-radius:9px;background:#17191e}.access p{margin:2px 0 0;color:#858c97;font-size:9px}.manage{padding:6px 9px;border:1px solid #39727c;border-radius:7px;background:#17262a;color:#90dfe8;font-size:9px}.chips{display:flex;flex-wrap:wrap;gap:5px;margin-top:9px}.chip{padding:3px 7px;border:1px solid var(--line2);border-radius:999px;color:#a8aeb8;font:8px var(--mono)}.chip.exclude{border-color:#624044;color:#e59a9b}.chip.required{border-color:#76573c;color:#e8ae79}.summary{display:grid;grid-template-columns:repeat(3,1fr);gap:8px;margin-top:11px}.metric{padding:10px;border:1px solid var(--line);border-radius:8px;background:#17191e}.metric span{display:block;color:#737a86;font:8px var(--mono);text-transform:uppercase}.metric strong{font-size:11px}.catalog{display:grid;grid-template-columns:170px minmax(0,1fr);min-height:390px;margin-top:12px;border:1px solid var(--line);border-radius:9px;overflow:hidden}.catalog-nav{padding:9px;border-right:1px solid var(--line);background:#15171b}.catalog-nav button{display:flex;width:100%;justify-content:space-between;padding:7px;border:0;border-radius:6px;background:transparent;color:#8f96a1;font-size:9px}.catalog-nav button.active{background:#252830;color:#e1e4e8}.catalog-main{padding:11px}.search{width:100%;padding:7px 8px;border:1px solid var(--line2);border-radius:7px;background:#15171b;color:#dfe2e7;font-size:9px}.group{margin-top:8px;border:1px solid var(--line);border-radius:7px;overflow:hidden}.group-head{display:flex;align-items:center;padding:8px 9px;background:#1b1e23}.group-head span{margin-left:auto;color:#777e89;font:8px var(--mono)}.item{display:grid;grid-template-columns:18px minmax(0,1fr) auto;gap:7px;align-items:start;padding:8px 9px;border-top:1px solid #292d35;font-size:9px}.item input{accent-color:var(--cyan)}.item small{display:block;color:#777e89;font-size:8px}.item-state{padding:2px 5px;border:1px solid var(--line);border-radius:999px;color:#8b929d;font:7.5px var(--mono)}.item-state.missing{border-color:#724144;color:#e68d8e}.required-toggle{display:flex;align-items:center;gap:7px;margin-top:10px;padding:10px;border:1px solid #5f4835;border-radius:8px;background:#211b17;color:#d4b89f;font-size:9px}.required-toggle input{accent-color:var(--orange)}.matrix{display:grid;grid-template-columns:repeat(3,1fr);gap:10px}.note{padding:13px;border:1px solid var(--line);border-radius:9px;background:var(--surface)}.note span{color:var(--cyan);font:9px var(--mono);text-transform:uppercase}.note p{color:var(--muted);font-size:12px}.acceptance{padding-left:20px;color:#c5c9d0}.acceptance li+li{margin-top:5px}@media(max-width:760px){.mode-grid,.summary,.matrix{grid-template-columns:1fr}.access{grid-template-columns:1fr}.catalog{grid-template-columns:1fr}.catalog-nav{display:flex;overflow:auto;border-right:0;border-bottom:1px solid var(--line)}.catalog-nav button{flex:none;width:auto;gap:12px}.entity-link{display:none}table{display:block;overflow:auto}}
</style>
</head>
<body><div class="page">
  <nav class="doc-nav" aria-label="Agent 配置设计文档"><a href="./agent-configuration-ui.html">整体框架</a><a href="./agent-core-configuration-ui.html">基础配置</a><a href="./agent-capability-configuration-ui.html" aria-current="page">能力配置</a><a href="./agent-tool-configuration-ui.html">Programs 选择器</a></nav>
  <header><div class="eyebrow">Agent configuration · Capabilities</div><h1>Programs、Skills 与 MCP</h1><p class="lead">三类能力分别配置，但遵循同一条规则：Agent保存访问策略和稳定引用，实体内容由全局目录管理，Runtime只解析当前允许且实际可用的实体。</p></header>

  <section id="prototype"><h2>1. 能力配置原型</h2><p>点击分页查看三类能力。Programs只显示摘要并进入独立选择器；Skills和MCP使用相同的“模式 + 摘要 + 按需选择器”结构，但MCP额外区分required。</p>
    <div class="prototype"><div class="proto-head"><span class="avatar">A</span><div><h3>Default Agent</h3><p>Capabilities · changes affect new turns</p></div><span class="saved">Saved</span></div><div class="proto-tabs" role="tablist"><button class="proto-tab" role="tab" aria-selected="true" aria-controls="cap-programs" tabindex="0" data-target="cap-programs">Programs</button><button class="proto-tab" role="tab" aria-selected="false" aria-controls="cap-skills" tabindex="-1" data-target="cap-skills">Skills</button><button class="proto-tab" role="tab" aria-selected="false" aria-controls="cap-mcp" tabindex="-1" data-target="cap-mcp">MCP</button></div><div class="proto-body">
      <div class="proto-panel" id="cap-programs" role="tabpanel"><div class="panel-head"><div><h3>Programs</h3><p>Functions、Workflows和Applications的调用范围。</p></div><a class="entity-link" href="./agent-tool-configuration-ui.html">Open full selector ↗</a></div><div class="mode-grid"><label class="mode"><input type="radio" name="program-mode" checked><strong>All Programs</strong><p>允许全部全局可用Programs；schema按需加载。</p></label><label class="mode"><input type="radio" name="program-mode"><strong>Selected scope</strong><p>只允许preset或手动选择项。</p></label><label class="mode"><input type="radio" name="program-mode"><strong>No Programs</strong><p>禁止Program registry调用。</p></label></div><div class="access"><div><h4>All Programs</h4><p>不在主页面渲染完整实体目录；打开选择器后才查询Functions、Workflows和Applications。</p><div class="chips"><span class="chip">77 available</span><span class="chip">schema on demand</span></div></div><a class="manage" href="./agent-tool-configuration-ui.html">Browse programs…</a></div></div>
      <div class="proto-panel" id="cap-skills" role="tabpanel" hidden><div class="panel-head"><div><h3>Skills</h3><p>控制可发现Skills；Skill说明与资源仍由Skills页面管理。</p></div><a class="entity-link" href="#skills">Open Skills design ↗</a></div><div class="mode-grid"><label class="mode"><input type="radio" name="skill-mode"><strong>All Skills</strong><p>允许全部当前可用Skills。</p></label><label class="mode"><input type="radio" name="skill-mode" checked><strong>Selected categories</strong><p>按类别允许，并可单独排除。</p></label><label class="mode"><input type="radio" name="skill-mode"><strong>No Skills</strong><p>不发现或加载任何Skill。</p></label></div><div class="access"><div><h4>Research, Writing, Code, Media</h4><p>42个Skills符合类别规则；3个明确排除项优先于类别允许。</p><div class="chips"><span class="chip">research</span><span class="chip">writing</span><span class="chip">code</span><span class="chip">media</span><span class="chip exclude">− serverless-modal</span><span class="chip exclude">− vast-gpu</span></div></div><button class="manage" type="button" data-open-catalog="skill-catalog">Manage Skills…</button></div><div class="catalog" id="skill-catalog" hidden><nav class="catalog-nav"><button class="active" type="button">Categories <span>4</span></button><button type="button">Included <span>42</span></button><button type="button">Excluded <span>3</span></button><button type="button">Missing <span>1</span></button></nav><div class="catalog-main"><input class="search" placeholder="Search Skills…"><div class="group"><div class="group-head"><strong>Research</strong><span>12 selected</span></div><label class="item"><input type="checkbox" checked><span><strong>research-lit</strong><small>Search and analyze research papers.</small></span><span class="item-state">Available</span></label><label class="item"><input type="checkbox" checked><span><strong>novelty-check</strong><small>Verify idea novelty against recent literature.</small></span><span class="item-state">Available</span></label><label class="item"><input type="checkbox" checked disabled><span><strong>legacy-review</strong><small>Referenced by this Agent but no longer installed.</small></span><span class="item-state missing">Missing</span></label></div></div></div></div>
      <div class="proto-panel" id="cap-mcp" role="tabpanel" hidden><div class="panel-head"><div><h3>MCP</h3><p>允许连接的服务，以及Agent启动所必需的服务。</p></div><a class="entity-link" href="#mcp">Open MCP design ↗</a></div><div class="mode-grid"><label class="mode"><input type="radio" name="mcp-mode"><strong>All connected</strong><p>允许全部已连接MCP服务。</p></label><label class="mode"><input type="radio" name="mcp-mode" checked><strong>Selected services</strong><p>只允许手动选择的服务。</p></label><label class="mode"><input type="radio" name="mcp-mode"><strong>No MCP</strong><p>禁止所有MCP服务。</p></label></div><div class="access"><div><h4>filesystem, browser, memory</h4><p>3个服务已连接；linear已在配置中排除。</p><div class="chips"><span class="chip">filesystem</span><span class="chip">browser</span><span class="chip">memory</span><span class="chip exclude">− linear</span></div></div><button class="manage" type="button" data-open-catalog="mcp-catalog">Manage MCP…</button></div><div class="catalog" id="mcp-catalog" hidden><nav class="catalog-nav"><button class="active" type="button">Allowed <span>3</span></button><button type="button">Required <span>1</span></button><button type="button">Excluded <span>1</span></button><button type="button">Unavailable <span>1</span></button></nav><div class="catalog-main"><input class="search" placeholder="Search MCP services…"><div class="group"><div class="group-head"><strong>Local services</strong><span>2 allowed</span></div><label class="item"><input type="checkbox" checked><span><strong>filesystem</strong><small>Local filesystem service · connected.</small></span><span class="item-state">Connected</span></label><label class="item"><input type="checkbox" checked><span><strong>memory</strong><small>Persistent memory service · connected.</small></span><span class="item-state">Connected</span></label></div><label class="required-toggle"><input type="checkbox" checked><span><strong>Require filesystem</strong><br>Agent cannot start when this service is unavailable.</span></label></div></div></div>
    </div></div>
  </section>

  <section id="skills"><h2>2. Skills配置规则</h2><table><thead><tr><th>规则</th><th>语义</th><th>显示</th></tr></thead><tbody><tr><td><code>allowed</code>为空，<code>categories</code>为空</td><td>允许全部未被disabled命中的Skills</td><td>All Skills</td></tr><tr><td><code>categories</code>非空</td><td>只允许匹配类别的Skills，再应用disabled</td><td>Selected categories</td></tr><tr><td><code>allowed</code>非空</td><td>允许明确名称/pattern；与category策略的并集或交集必须由Runtime定死并在UI说明</td><td>Selected scope</td></tr><tr><td><code>disabled</code>命中</td><td>排除优先；即使category或allowed命中也不可用</td><td>Excluded chip</td></tr><tr><td>引用不存在</td><td>保留引用，标记Missing；用户保存后才能删除</td><td>Missing row</td></tr></tbody></table><div class="warning callout"><strong>需要先明确：</strong>当前AgentSpec同时提供allowed与categories，但现有注释没有定义二者是并集还是交集。生产UI实现前必须在Runtime和API中确立唯一语义，并用同一resolver返回预览数量。</div></section>

  <section id="mcp"><h2>3. MCP配置规则</h2><table><thead><tr><th>集合</th><th>含义</th><th>运行结果</th></tr></thead><tbody><tr><td>Allowed</td><td>Agent可以使用的MCP服务范围</td><td>服务已连接时，其工具可以进入按需发现</td></tr><tr><td>Disabled</td><td>明确禁止的服务；优先级高于allowed</td><td>即使全局已连接也不提供给Agent</td></tr><tr><td>Required</td><td>Agent启动必须可用的服务</td><td>任一required服务缺失时Agent状态为Cannot start，并列出缺失项</td></tr><tr><td>Credential</td><td>由全局MCP Servers页面管理</td><td>Agent页面不显示、复制或导出secret</td></tr></tbody></table><div class="callout"><strong>Required不是默认勾选：</strong>允许服务失败时可以降级运行；只有Agent逻辑无法在缺少该服务时正确执行，用户才将其标为required。</div></section>

  <section id="resolver"><h2>4. 统一解析流程</h2><div class="matrix"><article class="note"><span>1 · References</span><h3>读取Agent策略</h3><p>读取Programs、Skills和MCP的allowed、disabled、categories、required等稳定引用。</p></article><article class="note"><span>2 · Registry</span><h3>查询全局实体</h3><p>只从各自唯一registry取得当前存在、启用和可连接的实体，不使用页面缓存作为运行事实。</p></article><article class="note"><span>3 · Resolution</span><h3>统一生成结果</h3><p>同一个Runtime resolver返回available、excluded、missing和required-missing，供页面预览与Agent启动共同使用。</p></article></div><table><thead><tr><th>结果</th><th>UI行为</th><th>Runtime行为</th></tr></thead><tbody><tr><td>available</td><td>计数并允许在选择器中查看</td><td>进入按需发现范围</td></tr><tr><td>excluded</td><td>显示明确排除原因</td><td>拒绝调用</td></tr><tr><td>missing</td><td>保留引用，标红并提供Remove</td><td>不提供；非required时Agent仍可启动</td></tr><tr><td>required-missing</td><td>页头显示Cannot start</td><td>阻止Agent启动并返回缺失服务列表</td></tr></tbody></table></section>

  <section id="states"><h2>5. 交互与状态合同</h2><table><thead><tr><th>场景</th><th>预期行为</th></tr></thead><tbody><tr><td>主页面</td><td>只显示模式、摘要、计数和Manage入口；不常驻渲染完整实体目录。</td></tr><tr><td>打开选择器</td><td>按来源或类别分组，可搜索、筛选Included/Excluded/Missing；关闭后返回原滚动位置。</td></tr><tr><td>实体在另一页面被删除</td><td>重新解析后显示Missing，不自动修改AgentSpec。</td></tr><tr><td>全局连接状态变化</td><td>只更新可用状态，不改变allowed/disabled/required选择。</td></tr><tr><td>会话override</td><td>只允许进一步收窄能力，不能绕过Agent级disabled或required限制。</td></tr><tr><td>大目录</td><td>选择器分页或虚拟滚动；搜索和分组由API支持，不把全部schema下载到页面。</td></tr><tr><td>窄屏</td><td>来源导航变为横向筛选条；列表保持单列且所有操作可由键盘完成。</td></tr></tbody></table></section>

  <section id="acceptance"><h2>6. 验收条件</h2><ol class="acceptance"><li>Programs、Skills、MCP三页共享相同的主页面层级和保存状态，但保留各自不同语义。</li><li>主页面不渲染完整实体目录；用户点击Manage后才查询和显示选择器。</li><li>所有计数和预览来自与Runtime相同的resolver结果，而不是前端自行推导。</li><li>失效引用保留并显示Missing；不会因为页面打开而被删除。</li><li>MCP required缺失会明确阻止Agent启动；普通allowed服务缺失只产生降级状态。</li><li>Agent配置不包含Program schema、Skill正文、MCP server配置或凭据。</li><li>会话级override不能扩展Agent级禁止范围。</li></ol></section>
</div>
<script>(()=>{const tabs=[...document.querySelectorAll('[role="tab"]')],panels=[...document.querySelectorAll('[role="tabpanel"]')];const select=(tab,focus=false)=>{tabs.forEach(item=>{const active=item===tab;item.setAttribute('aria-selected',String(active));item.tabIndex=active?0:-1});panels.forEach(panel=>panel.hidden=panel.id!==tab.dataset.target);if(focus)tab.focus()};tabs.forEach((tab,index)=>{tab.addEventListener('click',()=>select(tab));tab.addEventListener('keydown',event=>{let next=index;if(event.key==='ArrowRight')next=(index+1)%tabs.length;else if(event.key==='ArrowLeft')next=(index-1+tabs.length)%tabs.length;else if(event.key==='Home')next=0;else if(event.key==='End')next=tabs.length-1;else return;event.preventDefault();select(tabs[next],true)})});document.querySelectorAll('[data-open-catalog]').forEach(button=>button.addEventListener('click',()=>{const catalog=document.getElementById(button.dataset.openCatalog),opening=catalog.hidden;catalog.hidden=!opening;button.textContent=opening?'Close selector':'Manage '+(button.dataset.openCatalog.startsWith('skill')?'Skills':'MCP')+'…'}))})();</script>
</body></html>