@piagent/platform 1.1.9 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/CHANGELOG.md +43 -1
  2. package/README.md +2 -2
  3. package/docs/command-reference-vietnamese.md +13 -4
  4. package/docs/distribution-standard.md +7 -7
  5. package/docs/mcp-and-tools.md +108 -2
  6. package/docs/model-options.md +10 -8
  7. package/docs/operator-manual-vietnamese.md +12 -12
  8. package/docs/publishing-for-teams.md +1 -0
  9. package/docs/quickstart-vietnamese.md +2 -2
  10. package/docs/release-install-policy.md +6 -6
  11. package/docs/security-threat-model.md +1 -1
  12. package/docs/team-onboarding.md +4 -4
  13. package/docs/vercel-docs-site.md +34 -4
  14. package/docs-site/architecture.html +152 -0
  15. package/docs-site/assets/docs.css +1001 -0
  16. package/docs-site/assets/docs.js +84 -0
  17. package/docs-site/commands.html +203 -0
  18. package/docs-site/content/architecture.html +29 -0
  19. package/docs-site/content/commands.html +80 -0
  20. package/docs-site/content/index.html +80 -0
  21. package/docs-site/content/mcp-approval.html +81 -0
  22. package/docs-site/content/mcp-auth.html +76 -0
  23. package/docs-site/content/mcp-servers.html +111 -0
  24. package/docs-site/content/mcp.html +120 -0
  25. package/docs-site/content/permissions.html +54 -0
  26. package/docs-site/content/profiles.html +68 -0
  27. package/docs-site/content/quickstart.html +144 -0
  28. package/docs-site/content/runtime.html +45 -0
  29. package/docs-site/content/scope.html +71 -0
  30. package/docs-site/content/security.html +51 -0
  31. package/docs-site/content/team.html +23 -0
  32. package/docs-site/content/workflows.html +47 -0
  33. package/docs-site/index.html +131 -1534
  34. package/docs-site/mcp-approval.html +204 -0
  35. package/docs-site/mcp-auth.html +199 -0
  36. package/docs-site/mcp-servers.html +234 -0
  37. package/docs-site/mcp.html +243 -0
  38. package/docs-site/permissions.html +177 -0
  39. package/docs-site/profiles.html +191 -0
  40. package/docs-site/quickstart.html +267 -0
  41. package/docs-site/runtime.html +168 -0
  42. package/docs-site/scope.html +194 -0
  43. package/docs-site/security.html +174 -0
  44. package/docs-site/team.html +142 -0
  45. package/docs-site/workflows.html +170 -0
  46. package/package.json +4 -2
  47. package/packages/piagent-core/capabilities/capability-core.js +17 -1
  48. package/packages/piagent-core/extensions/document-intake.ts +5 -5
  49. package/packages/piagent-core/extensions/piagent-guard.ts +316 -0
  50. package/packages/piagent-core/mcp/mcp-approval-store.js +175 -0
  51. package/packages/piagent-core/mcp/mcp-auth-readiness.js +197 -0
  52. package/packages/piagent-core/mcp/mcp-command-actions.js +291 -0
  53. package/packages/piagent-core/mcp/mcp-config-layers.js +133 -0
  54. package/packages/piagent-core/mcp/mcp-server-catalog.js +150 -0
  55. package/packages/piagent-core/mcp/mcp-server-entry.js +242 -0
  56. package/packages/piagent-core/mcp/mcp-session-view.js +185 -0
  57. package/packages/piagent-core/package.json +7 -3
  58. package/packages/piagent-core/prompts/model-options.md +8 -8
  59. package/scripts/build-docs-site.mjs +421 -0
  60. package/scripts/configure-model-scope.sh +2 -2
  61. package/scripts/configure-subagents.sh +1 -1
  62. package/scripts/install-global.sh +5 -5
  63. package/scripts/mcp-manage.mjs +567 -0
  64. package/scripts/piagent-cli.mjs +1 -1
  65. package/scripts/preview-docs-site.mjs +88 -0
  66. package/scripts/setup.sh +2 -2
  67. package/scripts/team-doctor.sh +18 -2
  68. package/scripts/verify-local.sh +46 -19
  69. package/scripts/verify-release-identity.mjs +8 -2
  70. package/scripts/configure-mcp.sh +0 -349
@@ -0,0 +1,168 @@
1
+ <!doctype html>
2
+ <html lang="vi">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
6
+ <title>Terminal commands cho operator · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="Nhóm command này chạy ngoài slash command, dùng cho setup, doctor, benchmark, capability và MCP." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/runtime" />
10
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
11
+ <meta property="og:title" content="Terminal commands cho operator · Pi Agent Platform Docs" />
12
+ <meta property="og:description" content="Nhóm command này chạy ngoài slash command, dùng cho setup, doctor, benchmark, capability và MCP." />
13
+ <meta property="og:url" content="https://piagent.io.vn/runtime" />
14
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
15
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
16
+ <link
17
+ href="https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap"
18
+ rel="stylesheet"
19
+ />
20
+ <link rel="stylesheet" href="/assets/docs.css" />
21
+ <script src="/assets/docs.js" defer></script>
22
+ </head>
23
+ <body>
24
+ <header class="topbar">
25
+ <a class="brand" href="/" aria-label="Pi Agent Platform">
26
+ <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
27
+ <span>Pi Agent Platform</span>
28
+ </a>
29
+ <div class="top-actions">
30
+ <span class="pill"><span class="pill-dot"></span>v1.2.0 docs</span>
31
+ <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
32
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
33
+ <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
34
+ </svg>
35
+ GitHub
36
+ </a>
37
+ <button class="button mobile-menu" type="button" data-menu>Lộ trình</button>
38
+ <a class="button" href="/commands">Commands</a>
39
+ </div>
40
+ </header>
41
+
42
+ <div class="layout with-toc">
43
+ <aside class="sidebar" data-sidebar>
44
+ <div class="sidebar-search" aria-label="Tìm trong tài liệu">
45
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
46
+ <path d="M10.8 18.1a7.3 7.3 0 1 1 0-14.6 7.3 7.3 0 0 1 0 14.6Zm5.3-1.7 4.4 4.4" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
47
+ </svg>
48
+ <input type="search" placeholder="Tìm trang" data-filter />
49
+ </div>
50
+
51
+ <nav aria-label="Tài liệu">
52
+ <div class="nav-group">
53
+ <p class="nav-title">Get started</p>
54
+ <a class="nav-link" href="/">Overview</a>
55
+ <a class="nav-link" href="/quickstart">Quickstart</a>
56
+ <a class="nav-link" href="/scope">Phạm vi platform</a>
57
+ </div>
58
+ <div class="nav-group">
59
+ <p class="nav-title">Build</p>
60
+ <a class="nav-link" href="/profiles">Project profile</a>
61
+ <a class="nav-link" href="/permissions">Permission modes</a>
62
+ <a class="nav-link" href="/commands">Command catalog</a>
63
+ <a class="nav-link" href="/workflows">Workflows</a>
64
+ </div>
65
+ <div class="nav-group">
66
+ <p class="nav-title">MCP</p>
67
+ <a class="nav-link" href="/mcp">MCP overview</a>
68
+ <a class="nav-link" href="/mcp-servers">Quản lý server</a>
69
+ <a class="nav-link" href="/mcp-auth">Auth và readiness</a>
70
+ <a class="nav-link" href="/mcp-approval">Approval gate</a>
71
+ </div>
72
+ <div class="nav-group">
73
+ <p class="nav-title">Operate</p>
74
+ <a class="nav-link" href="/security">Security model</a>
75
+ <a class="nav-link" href="/architecture">Architecture</a>
76
+ <a class="nav-link current" href="/runtime" aria-current="page">Runtime tools</a>
77
+ <a class="nav-link" href="/team">Team usage</a>
78
+ </div>
79
+ </nav>
80
+ </aside>
81
+
82
+ <main>
83
+ <div class="content-shell" data-article>
84
+ <nav class="breadcrumb" aria-label="Breadcrumb">
85
+ <a href="/">Docs</a>
86
+ <span aria-hidden="true">/</span>
87
+ <span>Operate</span>
88
+ <span aria-hidden="true">/</span>
89
+ <span>Runtime tools</span>
90
+ </nav>
91
+ <div class="page-head">
92
+ <h1>Terminal commands cho operator</h1>
93
+ <p>Nhóm command này chạy ngoài slash command, dùng cho setup, doctor, benchmark, capability và MCP.</p>
94
+ </div>
95
+ <section class="section">
96
+
97
+ <div class="command-grid">
98
+ <article class="command-card">
99
+ <header><span>Setup global</span><button class="clip-btn" data-clip="piagent-setup --mcp-preset core --subagents-preset safe">Lấy lệnh</button></header>
100
+ <pre><code>piagent-setup --mcp-preset core --subagents-preset safe</code></pre>
101
+ </article>
102
+ <article class="command-card">
103
+ <header><span>Full update</span><button class="clip-btn" data-clip="npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0&#10;npm install -g --ignore-scripts @piagent/platform@X.Y.Z&#10;piagent-install --stable --dry-run&#10;piagent-install --stable">Lấy lệnh</button></header>
104
+ <pre><code>npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
105
+ npm install -g --ignore-scripts @piagent/platform@X.Y.Z
106
+ piagent-install --stable --dry-run
107
+ piagent-install --stable</code></pre>
108
+ </article>
109
+ <article class="command-card">
110
+ <header><span>Pi package only</span><button class="clip-btn" data-clip="piagent-install --version vX.Y.Z --resolve-tag --dry-run&#10;piagent-install --version vX.Y.Z --resolve-tag">Lấy lệnh</button></header>
111
+ <pre><code>piagent-install --version vX.Y.Z --resolve-tag --dry-run
112
+ piagent-install --version vX.Y.Z --resolve-tag</code></pre>
113
+ </article>
114
+ <article class="command-card">
115
+ <header><span>Init project</span><button class="clip-btn" data-clip="piagent-init /path/to/project">Lấy lệnh</button></header>
116
+ <pre><code>piagent-init /path/to/project</code></pre>
117
+ </article>
118
+ <article class="command-card">
119
+ <header><span>Doctor</span><button class="clip-btn" data-clip="piagent-doctor /path/to/project">Lấy lệnh</button></header>
120
+ <pre><code>piagent-doctor /path/to/project</code></pre>
121
+ </article>
122
+ <article class="command-card">
123
+ <header><span>Trusted run</span><button class="clip-btn" data-clip="piagent-auto --full-access -p &quot;Run the trusted local benchmark suite.&quot;">Lấy lệnh</button></header>
124
+ <pre><code>piagent-auto --read-only -p "Scout payment mapping. Do not edit source."
125
+ piagent-auto --full-access -p "Run the trusted local benchmark suite."</code></pre>
126
+ </article>
127
+ <article class="command-card">
128
+ <header><span>Capabilities</span><button class="clip-btn" data-clip="piagent-capabilities catalog --check&#10;piagent-capabilities doctor --profile .pi/piagent-profile.json">Lấy lệnh</button></header>
129
+ <pre><code>piagent-capabilities catalog --check
130
+ piagent-capabilities doctor --profile .pi/piagent-profile.json</code></pre>
131
+ </article>
132
+ <article class="command-card">
133
+ <header><span>Verification</span><button class="clip-btn" data-clip="npm run verify&#10;npm test&#10;npm run typecheck">Lấy lệnh</button></header>
134
+ <pre><code>npm run verify
135
+ npm test
136
+ npm run typecheck</code></pre>
137
+ </article>
138
+ </div>
139
+ </section>
140
+ <nav class="pager" aria-label="Trang kế tiếp">
141
+ <a class="pager-prev" href="/architecture">
142
+ <span class="pager-label">Trước</span>
143
+ <span class="pager-title">Architecture</span>
144
+ </a>
145
+ <a class="pager-next" href="/team">
146
+ <span class="pager-label">Tiếp</span>
147
+ <span class="pager-title">Team usage</span>
148
+ </a>
149
+ </nav>
150
+
151
+ <footer class="footer">
152
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
153
+ <div class="footer-links" aria-label="External links">
154
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
155
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
156
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
157
+ </div>
158
+ </footer>
159
+ </div>
160
+ </main>
161
+
162
+ <aside class="toc" aria-label="Mục lục trang">
163
+ <p class="toc-title">Trên trang này</p>
164
+ <nav data-toc></nav>
165
+ </aside>
166
+ </div>
167
+ </body>
168
+ </html>
@@ -0,0 +1,194 @@
1
+ <!doctype html>
2
+ <html lang="vi">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
6
+ <title>Platform này nhận phần nào về mình · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="Agent coding CLI nào cũng đã có cơ chế governance riêng. Platform này không thay thế lớp đó — nó đóng gói một cách vận hành cụ thể trên Pi để mọi repo dùng lại." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/scope" />
10
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
11
+ <meta property="og:title" content="Platform này nhận phần nào về mình · Pi Agent Platform Docs" />
12
+ <meta property="og:description" content="Agent coding CLI nào cũng đã có cơ chế governance riêng. Platform này không thay thế lớp đó — nó đóng gói một cách vận hành cụ thể trên Pi để mọi repo dùng lại." />
13
+ <meta property="og:url" content="https://piagent.io.vn/scope" />
14
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
15
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
16
+ <link
17
+ href="https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap"
18
+ rel="stylesheet"
19
+ />
20
+ <link rel="stylesheet" href="/assets/docs.css" />
21
+ <script src="/assets/docs.js" defer></script>
22
+ </head>
23
+ <body>
24
+ <header class="topbar">
25
+ <a class="brand" href="/" aria-label="Pi Agent Platform">
26
+ <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
27
+ <span>Pi Agent Platform</span>
28
+ </a>
29
+ <div class="top-actions">
30
+ <span class="pill"><span class="pill-dot"></span>v1.2.0 docs</span>
31
+ <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
32
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
33
+ <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
34
+ </svg>
35
+ GitHub
36
+ </a>
37
+ <button class="button mobile-menu" type="button" data-menu>Lộ trình</button>
38
+ <a class="button" href="/commands">Commands</a>
39
+ </div>
40
+ </header>
41
+
42
+ <div class="layout with-toc">
43
+ <aside class="sidebar" data-sidebar>
44
+ <div class="sidebar-search" aria-label="Tìm trong tài liệu">
45
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
46
+ <path d="M10.8 18.1a7.3 7.3 0 1 1 0-14.6 7.3 7.3 0 0 1 0 14.6Zm5.3-1.7 4.4 4.4" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
47
+ </svg>
48
+ <input type="search" placeholder="Tìm trang" data-filter />
49
+ </div>
50
+
51
+ <nav aria-label="Tài liệu">
52
+ <div class="nav-group">
53
+ <p class="nav-title">Get started</p>
54
+ <a class="nav-link" href="/">Overview</a>
55
+ <a class="nav-link" href="/quickstart">Quickstart</a>
56
+ <a class="nav-link current" href="/scope" aria-current="page">Phạm vi platform</a>
57
+ </div>
58
+ <div class="nav-group">
59
+ <p class="nav-title">Build</p>
60
+ <a class="nav-link" href="/profiles">Project profile</a>
61
+ <a class="nav-link" href="/permissions">Permission modes</a>
62
+ <a class="nav-link" href="/commands">Command catalog</a>
63
+ <a class="nav-link" href="/workflows">Workflows</a>
64
+ </div>
65
+ <div class="nav-group">
66
+ <p class="nav-title">MCP</p>
67
+ <a class="nav-link" href="/mcp">MCP overview</a>
68
+ <a class="nav-link" href="/mcp-servers">Quản lý server</a>
69
+ <a class="nav-link" href="/mcp-auth">Auth và readiness</a>
70
+ <a class="nav-link" href="/mcp-approval">Approval gate</a>
71
+ </div>
72
+ <div class="nav-group">
73
+ <p class="nav-title">Operate</p>
74
+ <a class="nav-link" href="/security">Security model</a>
75
+ <a class="nav-link" href="/architecture">Architecture</a>
76
+ <a class="nav-link" href="/runtime">Runtime tools</a>
77
+ <a class="nav-link" href="/team">Team usage</a>
78
+ </div>
79
+ </nav>
80
+ </aside>
81
+
82
+ <main>
83
+ <div class="content-shell" data-article>
84
+ <nav class="breadcrumb" aria-label="Breadcrumb">
85
+ <a href="/">Docs</a>
86
+ <span aria-hidden="true">/</span>
87
+ <span>Get started</span>
88
+ <span aria-hidden="true">/</span>
89
+ <span>Phạm vi platform</span>
90
+ </nav>
91
+ <div class="page-head">
92
+ <h1>Platform này nhận phần nào về mình</h1>
93
+ <p>Agent coding CLI nào cũng đã có cơ chế governance riêng. Platform này không thay thế lớp đó — nó đóng gói một cách vận hành cụ thể trên Pi để mọi repo dùng lại.</p>
94
+ </div>
95
+ <section class="section">
96
+ <h2 id="khong-phai-agent-moi">Đây không phải một agent mới</h2>
97
+ <p>Platform này không có model riêng, không có runtime riêng, không có vòng lặp agent riêng. Nó chạy như extension của Pi và chỉ thêm đúng một thứ: <strong>một cách vận hành cố định</strong> mà mọi repo trong team dùng lại được.</p>
98
+ <p>Agent coding CLI tổng quát nào cũng đã có sandbox, approval và cơ chế cấu hình theo project. Câu hỏi đáng hỏi không phải "cái nào mạnh hơn" mà là "cái đó cấu hình được, nhưng ai cấu hình, và cấu hình đó có giống nhau giữa 20 repo không".</p>
99
+
100
+ <div class="table-wrap">
101
+ <table>
102
+ <thead>
103
+ <tr>
104
+ <th>Hạng mục</th>
105
+ <th>Agent CLI tổng quát đã có</th>
106
+ <th>Platform này thêm</th>
107
+ </tr>
108
+ </thead>
109
+ <tbody>
110
+ <tr>
111
+ <td>Vai trò</td>
112
+ <td>Coding agent chạy trên local repo, tự chọn tool và tự chạy lệnh.</td>
113
+ <td>Lớp governance cho Pi: policy, profile và workflow vận hành được ghi thành file, không nằm trong prompt.</td>
114
+ </tr>
115
+ <tr>
116
+ <td>Tuỳ biến team</td>
117
+ <td>File hướng dẫn, settings, permission, hooks, skills, MCP — mỗi repo tự khai.</td>
118
+ <td>Adapter profile, base policy, command guard, capability pack, docs và scripts — khai một lần, <span class="inline-code">piagent-init</span> rải sang repo mới.</td>
119
+ </tr>
120
+ <tr>
121
+ <td>Quyền chạy</td>
122
+ <td>Sandbox ở mức OS hoặc process, approval theo lượt, giới hạn thư mục làm việc.</td>
123
+ <td>Ba mode đặt tên sẵn — <span class="inline-code">read-only</span>, <span class="inline-code">workspace-write</span>, <span class="inline-code">trusted-full-access</span> — đổi bằng một command, không sửa file nào.</td>
124
+ </tr>
125
+ <tr>
126
+ <td>Bảo mật secret</td>
127
+ <td>Sandbox, approval và network policy ở lớp dưới tool.</td>
128
+ <td>Policy ở lớp application, chạy sau khi tool được gọi: protected path, shell check, symlink alias, output redaction, integrity lock.</td>
129
+ </tr>
130
+ <tr>
131
+ <td>Điểm mạnh riêng</td>
132
+ <td>Trải nghiệm agent hoàn chỉnh, hệ sinh thái tool rộng.</td>
133
+ <td>Tính lặp lại: mọi repo cùng profile, cùng guard, cùng kỷ luật verify — và khác biệt thì thấy được vì nó nằm trong file.</td>
134
+ </tr>
135
+ </tbody>
136
+ </table>
137
+ </div>
138
+ </section>
139
+
140
+ <section class="section">
141
+ <h2 id="hai-lop-khong-thay-the-nhau">Hai lớp không thay thế nhau</h2>
142
+ <p>Sandbox của host chặn ở mức process: tiến trình không mở được file ngoài phạm vi cho phép. Guard của platform chặn ở mức lời gọi tool: nó đọc được <em>tham số</em> mà agent định dùng, nên biết lệnh đang đọc file nào, đang ghi ở đâu, đang gửi gì ra ngoài.</p>
143
+
144
+ <div class="split">
145
+ <div class="card">
146
+ <h3 id="lop-duoi">Lớp dưới thấy process</h3>
147
+ <p>Biết một tiến trình đang cố ghi ra ngoài workspace. Không biết tiến trình đó là <span class="inline-code">npm test</span> hay là một script vừa được sinh ra trong lượt này.</p>
148
+ </div>
149
+ <div class="card">
150
+ <h3 id="lop-tren">Lớp trên thấy ý định</h3>
151
+ <p>Biết tool nào, tham số nào, capability nào. Đủ để chặn <span class="inline-code">.env</span> theo tên, redact token trong output, và từ chối một MCP server mà repo mang theo.</p>
152
+ </div>
153
+ </div>
154
+
155
+ <div class="callout">
156
+ <strong>Bỏ lớp nào cũng hụt</strong>
157
+ <p>Guard ở lớp application không thay được sandbox: một tiến trình đã chạy rồi thì guard không với tới nữa. Ngược lại sandbox không biết <span class="inline-code">.env</span> khác gì <span class="inline-code">.env.example</span>. Platform này giả định lớp dưới vẫn bật.</p>
158
+ </div>
159
+ </section>
160
+
161
+ <section class="section">
162
+ <h2 id="khi-nao-khong-can">Khi nào không cần</h2>
163
+ <p>Một repo, một người, không secret nào đáng kể, không có ai khác phải làm theo cùng cách — thì cấu hình sẵn của Pi là đủ, và thêm một lớp nữa chỉ tốn thời gian đọc.</p>
164
+ <p>Platform này bắt đầu có lãi khi số repo đủ nhiều để không ai nhớ nổi repo nào đang mở quyền gì, hoặc khi câu "đã verify chưa" cần một câu trả lời giống nhau ở mọi repo.</p>
165
+ </section>
166
+ <nav class="pager" aria-label="Trang kế tiếp">
167
+ <a class="pager-prev" href="/quickstart">
168
+ <span class="pager-label">Trước</span>
169
+ <span class="pager-title">Quickstart</span>
170
+ </a>
171
+ <a class="pager-next" href="/profiles">
172
+ <span class="pager-label">Tiếp</span>
173
+ <span class="pager-title">Project profile</span>
174
+ </a>
175
+ </nav>
176
+
177
+ <footer class="footer">
178
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
179
+ <div class="footer-links" aria-label="External links">
180
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
181
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
182
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
183
+ </div>
184
+ </footer>
185
+ </div>
186
+ </main>
187
+
188
+ <aside class="toc" aria-label="Mục lục trang">
189
+ <p class="toc-title">Trên trang này</p>
190
+ <nav data-toc></nav>
191
+ </aside>
192
+ </div>
193
+ </body>
194
+ </html>
@@ -0,0 +1,174 @@
1
+ <!doctype html>
2
+ <html lang="vi">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
6
+ <title>Policy enforcement layer, không phải OS sandbox · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="Platform ưu tiên fail-closed trong bề mặt tool được kiểm soát: khi lock sai, profile sai hoặc bằng chứng thiếu thì chặn, không đoán." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/security" />
10
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
11
+ <meta property="og:title" content="Policy enforcement layer, không phải OS sandbox · Pi Agent Platform Docs" />
12
+ <meta property="og:description" content="Platform ưu tiên fail-closed trong bề mặt tool được kiểm soát: khi lock sai, profile sai hoặc bằng chứng thiếu thì chặn, không đoán." />
13
+ <meta property="og:url" content="https://piagent.io.vn/security" />
14
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
15
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
16
+ <link
17
+ href="https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap"
18
+ rel="stylesheet"
19
+ />
20
+ <link rel="stylesheet" href="/assets/docs.css" />
21
+ <script src="/assets/docs.js" defer></script>
22
+ </head>
23
+ <body>
24
+ <header class="topbar">
25
+ <a class="brand" href="/" aria-label="Pi Agent Platform">
26
+ <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
27
+ <span>Pi Agent Platform</span>
28
+ </a>
29
+ <div class="top-actions">
30
+ <span class="pill"><span class="pill-dot"></span>v1.2.0 docs</span>
31
+ <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
32
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
33
+ <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
34
+ </svg>
35
+ GitHub
36
+ </a>
37
+ <button class="button mobile-menu" type="button" data-menu>Lộ trình</button>
38
+ <a class="button" href="/commands">Commands</a>
39
+ </div>
40
+ </header>
41
+
42
+ <div class="layout with-toc">
43
+ <aside class="sidebar" data-sidebar>
44
+ <div class="sidebar-search" aria-label="Tìm trong tài liệu">
45
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
46
+ <path d="M10.8 18.1a7.3 7.3 0 1 1 0-14.6 7.3 7.3 0 0 1 0 14.6Zm5.3-1.7 4.4 4.4" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
47
+ </svg>
48
+ <input type="search" placeholder="Tìm trang" data-filter />
49
+ </div>
50
+
51
+ <nav aria-label="Tài liệu">
52
+ <div class="nav-group">
53
+ <p class="nav-title">Get started</p>
54
+ <a class="nav-link" href="/">Overview</a>
55
+ <a class="nav-link" href="/quickstart">Quickstart</a>
56
+ <a class="nav-link" href="/scope">Phạm vi platform</a>
57
+ </div>
58
+ <div class="nav-group">
59
+ <p class="nav-title">Build</p>
60
+ <a class="nav-link" href="/profiles">Project profile</a>
61
+ <a class="nav-link" href="/permissions">Permission modes</a>
62
+ <a class="nav-link" href="/commands">Command catalog</a>
63
+ <a class="nav-link" href="/workflows">Workflows</a>
64
+ </div>
65
+ <div class="nav-group">
66
+ <p class="nav-title">MCP</p>
67
+ <a class="nav-link" href="/mcp">MCP overview</a>
68
+ <a class="nav-link" href="/mcp-servers">Quản lý server</a>
69
+ <a class="nav-link" href="/mcp-auth">Auth và readiness</a>
70
+ <a class="nav-link" href="/mcp-approval">Approval gate</a>
71
+ </div>
72
+ <div class="nav-group">
73
+ <p class="nav-title">Operate</p>
74
+ <a class="nav-link current" href="/security" aria-current="page">Security model</a>
75
+ <a class="nav-link" href="/architecture">Architecture</a>
76
+ <a class="nav-link" href="/runtime">Runtime tools</a>
77
+ <a class="nav-link" href="/team">Team usage</a>
78
+ </div>
79
+ </nav>
80
+ </aside>
81
+
82
+ <main>
83
+ <div class="content-shell" data-article>
84
+ <nav class="breadcrumb" aria-label="Breadcrumb">
85
+ <a href="/">Docs</a>
86
+ <span aria-hidden="true">/</span>
87
+ <span>Operate</span>
88
+ <span aria-hidden="true">/</span>
89
+ <span>Security model</span>
90
+ </nav>
91
+ <div class="page-head">
92
+ <h1>Policy enforcement layer, không phải OS sandbox</h1>
93
+ <p>Platform ưu tiên fail-closed trong bề mặt tool được kiểm soát: khi lock sai, profile sai hoặc bằng chứng thiếu thì chặn, không đoán.</p>
94
+ </div>
95
+ <section class="section">
96
+
97
+ <div class="grid cols-2">
98
+ <article class="card">
99
+ <h3 id="protected-paths">Protected paths</h3>
100
+ <p>Chặn đọc/ghi qua controlled tools đối với file như <span class="inline-code">.env</span>, <span class="inline-code">auth.json</span>, local trust files, profile lock và settings nhạy cảm.</p>
101
+ </article>
102
+ <article class="card">
103
+ <h3 id="shell-hardening">Shell hardening</h3>
104
+ <p>Guard dựa vào shell parser và rule cho command được kiểm soát để bắt glob, brace, redirection, bare-word symlink và xargs composition trước khi shell mở rộng runtime.</p>
105
+ </article>
106
+ <article class="card">
107
+ <h3 id="secret-redaction">Secret redaction</h3>
108
+ <p>Tool output text đi qua redactor để che token, provider keys, secret keyword patterns và giá trị nhạy cảm phổ biến. Benchmark hiện là synthetic/internal và model vẫn đang hoàn thiện.</p>
109
+ </article>
110
+ <article class="card">
111
+ <h3 id="capability-lock">Capability lock</h3>
112
+ <p>Pack lock có digest và tamper detection. Lock hỏng thì fail-closed, không tự nới quyền.</p>
113
+ </article>
114
+ <article class="card">
115
+ <h3 id="human-action-gate">Human-action gate</h3>
116
+ <p>Destructive hoặc external-provider action vẫn cần operator xác nhận rõ, kể cả khi full-access đang bật. Gate áp dụng cho direct tool, MCP proxy đã decode và các shell form như GitHub CLI write hoặc HTTP non-GET.</p>
117
+ </article>
118
+ <article class="card">
119
+ <h3 id="verify-evidence">Verify evidence</h3>
120
+ <p>Handoff hoàn tất cần bằng chứng verify từ bash result đã quan sát, không nhận câu trả lời “đã test” suông.</p>
121
+ </article>
122
+ </div>
123
+
124
+ <div class="callout">
125
+ <strong>Ranh giới quan trọng</strong>
126
+ <p>Guard phụ thuộc vào tool path, controlled tools và shell parser mà platform quan sát được. Nó không ngăn một process khác chạy cùng quyền OS đọc/ghi ngoài guard, và không thay thế sandbox của hệ điều hành.</p>
127
+ <ul>
128
+ <li>Có thể bị ảnh hưởng bởi symlink, encoding, nested payload, shell expansion hoặc tool mới chưa được policy hoá.</li>
129
+ <li>Redaction là backstop giảm rò rỉ, không phải giấy phép để đưa secret thật vào prompt/output.</li>
130
+ <li>Workload không tin cậy cần container/VM với giới hạn filesystem, process, network và credential.</li>
131
+ </ul>
132
+ </div>
133
+
134
+ <div class="callout">
135
+ <strong>Redaction cần kiểm toán độc lập</strong>
136
+ <p>Các benchmark hiện tại là kiểm thử synthetic/internal cho regression và release gate, chưa tương đương external security audit. Dự án công khai <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/security-threat-model.md" target="_blank" rel="noopener noreferrer">threat model và attack-vector map</a>; phạm vi OS/shell rộng hơn, parser fuzzing, third-party audit và LTS vẫn là các mức bảo đảm cao hơn chưa được claim. Signed provenance thì đã có: mỗi bản publish lên npm mang attestation ký qua sigstore từ GitHub Actions, buộc tarball về đúng commit và workflow tạo ra nó.</p>
137
+ </div>
138
+
139
+ <div class="callout">
140
+ <strong>Dependency gate tách hai lớp</strong>
141
+ <p>Release kiểm toán riêng dependency tree nhỏ của terminal helper và cây exact Pi host + pinned add-on. Helper tree hiện sạch hoàn toàn. Cây Pi host có 1 high và 11 moderate, và dự án nói thẳng con số đó thay vì gọi runtime là “0 vulnerability”.</p>
142
+ <p>Bản high là <span class="inline-code">GHSA-mh99-v99m-4gvg</span> trong <span class="inline-code">brace-expansion</span> — DoS, không leo quyền, không lộ dữ liệu. Repo này không sửa được: Pi host publish kèm <span class="inline-code">npm-shrinkwrap.json</span> ghim version dính lỗi, mà shrinkwrap đã publish thì thắng <span class="inline-code">overrides</span> của consumer. Mọi bản Pi đã phát hành đều dính một advisory brace-expansion, nên pin bản cũ chỉ đổi lỗi này lấy lỗi khác. Vì vậy gate miễn trừ đúng một advisory có tên, kèm lý do ghi trong mã nguồn, và tự đỏ lại khi hết hạn rà soát <span class="inline-code">2026-08-25</span> hoặc ngay khi upstream vá xong. Mọi high/critical khác vẫn chặn.</p>
143
+ <p>11 moderate còn lại thuộc hai advisory upstream: encoded-backslash path traversal trên Windows trong Hono adapter, và protobuf parser DoS. Native Windows/WSL2 chưa nằm trong matrix rollout team, nhưng dự án vẫn theo dõi cả hai.</p>
144
+ </div>
145
+ </section>
146
+ <nav class="pager" aria-label="Trang kế tiếp">
147
+ <a class="pager-prev" href="/mcp-approval">
148
+ <span class="pager-label">Trước</span>
149
+ <span class="pager-title">Approval gate</span>
150
+ </a>
151
+ <a class="pager-next" href="/architecture">
152
+ <span class="pager-label">Tiếp</span>
153
+ <span class="pager-title">Architecture</span>
154
+ </a>
155
+ </nav>
156
+
157
+ <footer class="footer">
158
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
159
+ <div class="footer-links" aria-label="External links">
160
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
161
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
162
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
163
+ </div>
164
+ </footer>
165
+ </div>
166
+ </main>
167
+
168
+ <aside class="toc" aria-label="Mục lục trang">
169
+ <p class="toc-title">Trên trang này</p>
170
+ <nav data-toc></nav>
171
+ </aside>
172
+ </div>
173
+ </body>
174
+ </html>