@piagent/platform 1.1.8 → 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 (71) hide show
  1. package/CHANGELOG.md +51 -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 +2 -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 +319 -4
  50. package/packages/piagent-core/extensions/update-check.js +41 -0
  51. package/packages/piagent-core/mcp/mcp-approval-store.js +175 -0
  52. package/packages/piagent-core/mcp/mcp-auth-readiness.js +197 -0
  53. package/packages/piagent-core/mcp/mcp-command-actions.js +291 -0
  54. package/packages/piagent-core/mcp/mcp-config-layers.js +133 -0
  55. package/packages/piagent-core/mcp/mcp-server-catalog.js +150 -0
  56. package/packages/piagent-core/mcp/mcp-server-entry.js +242 -0
  57. package/packages/piagent-core/mcp/mcp-session-view.js +185 -0
  58. package/packages/piagent-core/package.json +7 -3
  59. package/packages/piagent-core/prompts/model-options.md +8 -8
  60. package/scripts/build-docs-site.mjs +421 -0
  61. package/scripts/configure-model-scope.sh +2 -2
  62. package/scripts/configure-subagents.sh +1 -1
  63. package/scripts/install-global.sh +5 -5
  64. package/scripts/mcp-manage.mjs +567 -0
  65. package/scripts/piagent-cli.mjs +1 -1
  66. package/scripts/preview-docs-site.mjs +88 -0
  67. package/scripts/setup.sh +2 -2
  68. package/scripts/team-doctor.sh +18 -2
  69. package/scripts/verify-local.sh +46 -19
  70. package/scripts/verify-release-identity.mjs +8 -2
  71. package/scripts/configure-mcp.sh +0 -349
package/docs-site/permissions.html ADDED
@@ -0,0 +1,177 @@
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>Một command để đổi quyền theo task · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="Permission mode là session-local override. Đổi mode không sửa project profile." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/permissions" />
10
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
11
+ <meta property="og:title" content="Một command để đổi quyền theo task · Pi Agent Platform Docs" />
12
+ <meta property="og:description" content="Permission mode là session-local override. Đổi mode không sửa project profile." />
13
+ <meta property="og:url" content="https://piagent.io.vn/permissions" />
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 current" href="/permissions" aria-current="page">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>Build</span>
88
+ <span aria-hidden="true">/</span>
89
+ <span>Permission modes</span>
90
+ </nav>
91
+ <div class="page-head">
92
+ <h1>Một command để đổi quyền theo task</h1>
93
+ <p>Permission mode là session-local override. Đổi mode không sửa project profile.</p>
94
+ </div>
95
+ <section class="section">
96
+
97
+ <div class="table-wrap">
98
+ <table>
99
+ <thead>
100
+ <tr>
101
+ <th>Mode</th>
102
+ <th>Dùng khi nào</th>
103
+ <th>Ranh giới</th>
104
+ <th>Command</th>
105
+ </tr>
106
+ </thead>
107
+ <tbody>
108
+ <tr>
109
+ <td><span class="inline-code">read-only</span></td>
110
+ <td>Scout, audit, mapping, review không chỉnh source.</td>
111
+ <td>Cho read, grep, find, ls và piagent tools; chặn shell/write/unknown tools.</td>
112
+ <td><span class="inline-code">/read-only</span></td>
113
+ </tr>
114
+ <tr>
115
+ <td><span class="inline-code">workspace-write</span></td>
116
+ <td>Implementation bình thường trong repo.</td>
117
+ <td>Default guarded mode; giữ protected path, shell policy, capability và verify gate.</td>
118
+ <td><span class="inline-code">/workspace-write</span></td>
119
+ </tr>
120
+ <tr>
121
+ <td><span class="inline-code">trusted-full-access</span></td>
122
+ <td>Automation trên repo đã tin và task đã rõ.</td>
123
+ <td>Nới autonomy trong guard, nhưng vẫn giữ protected path, redaction, lock và confirmation.</td>
124
+ <td><span class="inline-code">/full-access</span></td>
125
+ </tr>
126
+ </tbody>
127
+ </table>
128
+ </div>
129
+
130
+ <div class="command-grid">
131
+ <article class="command-card">
132
+ <header><span>Xem permission</span><button class="clip-btn" data-clip="/permission-status">Lấy lệnh</button></header>
133
+ <pre><code>/permission-status</code></pre>
134
+ </article>
135
+ <article class="command-card">
136
+ <header><span>Read-only session</span><button class="clip-btn" data-clip="/read-only">Lấy lệnh</button></header>
137
+ <pre><code>/read-only</code></pre>
138
+ </article>
139
+ <article class="command-card">
140
+ <header><span>Workspace write</span><button class="clip-btn" data-clip="/workspace-write">Lấy lệnh</button></header>
141
+ <pre><code>/workspace-write</code></pre>
142
+ </article>
143
+ <article class="command-card">
144
+ <header><span>Full-access + task</span><button class="clip-btn" data-clip="/full-access Run the trusted local verification suite.">Lấy lệnh</button></header>
145
+ <pre><code>/full-access Run the trusted local verification suite.</code></pre>
146
+ </article>
147
+ </div>
148
+ </section>
149
+ <nav class="pager" aria-label="Trang kế tiếp">
150
+ <a class="pager-prev" href="/profiles">
151
+ <span class="pager-label">Trước</span>
152
+ <span class="pager-title">Project profile</span>
153
+ </a>
154
+ <a class="pager-next" href="/commands">
155
+ <span class="pager-label">Tiếp</span>
156
+ <span class="pager-title">Command catalog</span>
157
+ </a>
158
+ </nav>
159
+
160
+ <footer class="footer">
161
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
162
+ <div class="footer-links" aria-label="External links">
163
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
164
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
165
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
166
+ </div>
167
+ </footer>
168
+ </div>
169
+ </main>
170
+
171
+ <aside class="toc" aria-label="Mục lục trang">
172
+ <p class="toc-title">Trên trang này</p>
173
+ <nav data-toc></nav>
174
+ </aside>
175
+ </div>
176
+ </body>
177
+ </html>
package/docs-site/profiles.html ADDED
@@ -0,0 +1,191 @@
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>Chọn đúng đường ray cho repo · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="Profile ghi vào .pi/piagent-profile.json và lock tương ứng. Nó quyết định protected path, verify command và capability mà project cấp." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/profiles" />
10
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
11
+ <meta property="og:title" content="Chọn đúng đường ray cho repo · Pi Agent Platform Docs" />
12
+ <meta property="og:description" content="Profile ghi vào .pi/piagent-profile.json và lock tương ứng. Nó quyết định protected path, verify command và capability mà project cấp." />
13
+ <meta property="og:url" content="https://piagent.io.vn/profiles" />
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 current" href="/profiles" aria-current="page">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>Build</span>
88
+ <span aria-hidden="true">/</span>
89
+ <span>Project profile</span>
90
+ </nav>
91
+ <div class="page-head">
92
+ <h1>Chọn đúng đường ray cho repo</h1>
93
+ <p>Profile ghi vào .pi/piagent-profile.json và lock tương ứng. Nó quyết định protected path, verify command và capability mà project cấp.</p>
94
+ </div>
95
+ <section class="section">
96
+
97
+ <div class="command-grid">
98
+ <article class="command-card">
99
+ <header><span>Xem status ngắn</span><button class="clip-btn" data-clip="/profile">Lấy lệnh</button></header>
100
+ <pre><code>/profile</code></pre>
101
+ </article>
102
+ <article class="command-card">
103
+ <header><span>Liệt kê options</span><button class="clip-btn" data-clip="/profile list">Lấy lệnh</button></header>
104
+ <pre><code>/profile list</code></pre>
105
+ </article>
106
+ <article class="command-card">
107
+ <header><span>Áp profile detect</span><button class="clip-btn" data-clip="/profile auto">Lấy lệnh</button></header>
108
+ <pre><code>/profile auto</code></pre>
109
+ </article>
110
+ <article class="command-card">
111
+ <header><span>Setup bằng select</span><button class="clip-btn" data-clip="/profile setup&#10;/profile tech setup fullstack">Lấy lệnh</button></header>
112
+ <pre><code>/profile setup
113
+ /profile tech setup fullstack</code></pre>
114
+ </article>
115
+ <article class="command-card">
116
+ <header><span>Apply tech deterministic</span><button class="clip-btn" data-clip="/profile tech apply fullstack frontend=nextjs backend=nestjs database=prisma">Lấy lệnh</button></header>
117
+ <pre><code>/profile tech apply fullstack frontend=nextjs backend=nestjs database=prisma</code></pre>
118
+ </article>
119
+ <article class="command-card">
120
+ <header><span>Frontend</span><button class="clip-btn" data-clip="/profile web-frontend">Lấy lệnh</button></header>
121
+ <pre><code>/profile web-frontend
122
+ /profile fe</code></pre>
123
+ </article>
124
+ <article class="command-card">
125
+ <header><span>Backend/API</span><button class="clip-btn" data-clip="/profile backend-api">Lấy lệnh</button></header>
126
+ <pre><code>/profile backend-api</code></pre>
127
+ </article>
128
+ <article class="command-card">
129
+ <header><span>Backend read-only, frontend write</span><button class="clip-btn" data-clip="/profile be-readonly-fe">Lấy lệnh</button></header>
130
+ <pre><code>/profile be-readonly-fe
131
+ /profile be-fe</code></pre>
132
+ </article>
133
+ <article class="command-card">
134
+ <header><span>Fullstack</span><button class="clip-btn" data-clip="/profile fullstack">Lấy lệnh</button></header>
135
+ <pre><code>/profile fullstack
136
+ /profile full</code></pre>
137
+ </article>
138
+ <article class="command-card">
139
+ <header><span>Docs-only</span><button class="clip-btn" data-clip="/profile docs">Lấy lệnh</button></header>
140
+ <pre><code>/profile docs</code></pre>
141
+ </article>
142
+ </div>
143
+
144
+ <div class="tag-list">
145
+ <span class="tag">generic</span>
146
+ <span class="tag">node-typescript</span>
147
+ <span class="tag">python</span>
148
+ <span class="tag">web-frontend</span>
149
+ <span class="tag">backend-api</span>
150
+ <span class="tag">fullstack</span>
151
+ <span class="tag">be-readonly-fe</span>
152
+ <span class="tag">data</span>
153
+ <span class="tag">devops</span>
154
+ <span class="tag">mobile</span>
155
+ <span class="tag">docs</span>
156
+ </div>
157
+
158
+ <div class="callout">
159
+ <strong>Tech stack theo role</strong>
160
+ <p>Frontend profile chọn FE + database optional; backend profile chọn BE + database optional; fullstack chọn đủ FE, BE và database. Sau đó platform tạo <span class="inline-code">.pi/tech-stack.json</span> và snapshot Context7 ngắn trong <span class="inline-code">.pi/tech-context/*</span>.</p>
161
+ </div>
162
+ </section>
163
+ <nav class="pager" aria-label="Trang kế tiếp">
164
+ <a class="pager-prev" href="/scope">
165
+ <span class="pager-label">Trước</span>
166
+ <span class="pager-title">Phạm vi platform</span>
167
+ </a>
168
+ <a class="pager-next" href="/permissions">
169
+ <span class="pager-label">Tiếp</span>
170
+ <span class="pager-title">Permission modes</span>
171
+ </a>
172
+ </nav>
173
+
174
+ <footer class="footer">
175
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
176
+ <div class="footer-links" aria-label="External links">
177
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
178
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
179
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
180
+ </div>
181
+ </footer>
182
+ </div>
183
+ </main>
184
+
185
+ <aside class="toc" aria-label="Mục lục trang">
186
+ <p class="toc-title">Trên trang này</p>
187
+ <nav data-toc></nav>
188
+ </aside>
189
+ </div>
190
+ </body>
191
+ </html>
package/docs-site/quickstart.html ADDED
@@ -0,0 +1,267 @@
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>Step by step cho thành viên mới · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="Hai lệnh để cài, rồi mở repo, chọn profile, bật quyền phù hợp, chạy task, và verify bằng bằng chứng thật trước khi handoff." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/quickstart" />
10
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
11
+ <meta property="og:title" content="Step by step cho thành viên mới · Pi Agent Platform Docs" />
12
+ <meta property="og:description" content="Hai lệnh để cài, rồi mở repo, chọn profile, bật quyền phù hợp, chạy task, và verify bằng bằng chứng thật trước khi handoff." />
13
+ <meta property="og:url" content="https://piagent.io.vn/quickstart" />
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 current" href="/quickstart" aria-current="page">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" 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>Quickstart</span>
90
+ </nav>
91
+ <div class="page-head">
92
+ <h1>Step by step cho thành viên mới</h1>
93
+ <p>Hai lệnh để cài, rồi mở repo, chọn profile, bật quyền phù hợp, chạy task, và verify bằng bằng chứng thật trước khi handoff.</p>
94
+ </div>
95
+ <section class="section">
96
+
97
+ <div class="steps">
98
+ <article class="step">
99
+ <div>
100
+ <h3 id="cai-hai-lenh">Cài — hai lệnh</h3>
101
+ <p>Cần Node.js 22.19.0 trở lên. Không cần cài Pi Coding Agent trước: <span class="inline-code">piagent-setup</span> tự cài đúng bản <span class="inline-code">0.82.0</span> mà release <span class="inline-code">v1.2.0</span> đang pin. Chạy nó ngay trong thư mục project — nó cài Pi package, khởi tạo <span class="inline-code">.pi/</span>, cài MCP baseline cùng subagents, rồi chạy doctor. Thêm <span class="inline-code">--no-mcp</span>, <span class="inline-code">--no-subagents</span>, <span class="inline-code">--no-herdr</span> hoặc <span class="inline-code">--global-only</span> để bỏ bớt.</p>
102
+ <div class="table-wrap compact-table">
103
+ <table>
104
+ <thead>
105
+ <tr>
106
+ <th>Runtime</th>
107
+ <th>Trạng thái rollout</th>
108
+ </tr>
109
+ </thead>
110
+ <tbody>
111
+ <tr>
112
+ <td>macOS Apple Silicon + Bash</td>
113
+ <td>Đã verify cho release này.</td>
114
+ </tr>
115
+ <tr>
116
+ <td>Linux x64 + Bash</td>
117
+ <td>Đã verify trong CI.</td>
118
+ </tr>
119
+ <tr>
120
+ <td>macOS Intel / Linux ARM64 + Bash</td>
121
+ <td>Supported target; chạy doctor + smoke test trước khi rollout rộng.</td>
122
+ </tr>
123
+ <tr>
124
+ <td>Native Windows / WSL2</td>
125
+ <td>Chưa là target rollout team; WSL2 chỉ experimental.</td>
126
+ </tr>
127
+ </tbody>
128
+ </table>
129
+ </div>
130
+ <div class="command-card">
131
+ <header><span>Hai lệnh</span><button class="clip-btn" data-clip="npm install -g @piagent/platform&#10;piagent-setup">Lấy lệnh</button></header>
132
+ <pre><code>npm install -g @piagent/platform
133
+ piagent-setup</code></pre>
134
+ </div>
135
+ <p>Vì chạy từ package đã cài, source ghi vào <span class="inline-code">.pi/settings.json</span> là <span class="inline-code">npm:@piagent/platform@&lt;version&gt;</span> — giá trị này có nghĩa như nhau trên máy đồng đội, nên commit được cho cả team.</p>
136
+ <p>Dùng <a href="https://herdr.dev/docs/install/">Herdr</a> thì cài Herdr <strong>trước</strong>: <span class="inline-code">piagent-setup</span> tự cài luôn Herdr Pi integration khi thấy <span class="inline-code">herdr</span> trên <span class="inline-code">PATH</span>, còn không thì bỏ qua kèm cảnh báo — cài Herdr sau phải chạy lại <span class="inline-code">piagent-setup --global-only</span>.</p>
137
+ <div class="command-card">
138
+ <header><span>Herdr (tuỳ chọn, cài trước)</span><button class="clip-btn" data-clip="brew install herdr">Lấy lệnh</button></header>
139
+ <pre><code>brew install herdr # macOS
140
+ curl -fsSL https://herdr.dev/install.sh | sh # macOS hoặc Linux</code></pre>
141
+ </div>
142
+ <p>Bản <span class="inline-code">curl</span> chạy script tải về lúc cài; muốn kiểm tra được thì dùng <span class="inline-code">brew</span> hoặc tải từ <a href="https://github.com/ogulcancelik/herdr/releases">GitHub releases</a>. Herdr stable hỗ trợ macOS và Linux, Windows mới ở mức preview.</p>
143
+ <p>Rollout pin từng bước, update, rollback, và channel latest cho máy cá nhân nằm trong <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/release-install-policy.md">release &amp; install policy</a>.</p>
144
+ </div>
145
+ </article>
146
+
147
+ <article class="step">
148
+ <div>
149
+ <h3 id="mo-repo-du-an">Mở repo dự án</h3>
150
+ <p>Chạy Pi từ thư mục repo. Với repo đã tin cậy, dùng wrapper trusted-run khi cần tự động hoá có kiểm soát.</p>
151
+ <div class="command-card">
152
+ <header><span>Start</span><button class="clip-btn" data-clip="cd /path/to/project && pi">Lấy lệnh</button></header>
153
+ <pre><code>cd /path/to/project
154
+ pi</code></pre>
155
+ </div>
156
+ <p>Cần nhiều agent chạy song song thì gõ <span class="inline-code">herdr</span> thay cho <span class="inline-code">pi</span>, mỗi pane một vai: implement, review read-only, verify, notes. Herdr chỉ điều phối terminal và session — nó không phải security boundary, gate vẫn nằm ở Pi extension và OAuth vẫn login trong Pi. Cách dựng pane: <a href="https://github.com/Vt-mmm/piagent/blob/main/docs/herdr-workflow.md">Herdr workflow</a>.</p>
157
+ </div>
158
+ </article>
159
+
160
+ <article class="step">
161
+ <div>
162
+ <h3 id="onboard-context">Onboard context</h3>
163
+ <p>Chạy một lần ở repo mới để ghi context, verify matrix và protected areas vào <span class="inline-code">.pi/</span>.</p>
164
+ <div class="command-card">
165
+ <header><span>Onboard</span><button class="clip-btn" data-clip="/onboard-project">Lấy lệnh</button></header>
166
+ <pre><code>/onboard-project</code></pre>
167
+ </div>
168
+ </div>
169
+ </article>
170
+
171
+ <article class="step">
172
+ <div>
173
+ <h3 id="chon-profile-tech">Chọn profile + tech</h3>
174
+ <p>Dùng <span class="inline-code">/profile setup</span> để mở select option: chọn profile trước, rồi chọn tech theo role. Fullstack sẽ chọn frontend, backend và database.</p>
175
+ <div class="command-card">
176
+ <header><span>Profile tech setup</span><button class="clip-btn" data-clip="/profile setup&#10;/profile tech setup fullstack">Lấy lệnh</button></header>
177
+ <pre><code>/profile setup
178
+ /profile tech setup fullstack</code></pre>
179
+ </div>
180
+ </div>
181
+ </article>
182
+
183
+ <article class="step">
184
+ <div>
185
+ <h3 id="chon-permission">Chọn permission</h3>
186
+ <p>Scout thì read-only, code bình thường thì workspace-write, automation tin cậy thì full-access có guard.</p>
187
+ <div class="command-card">
188
+ <header><span>Permission</span><button class="clip-btn" data-clip="/workspace-write">Lấy lệnh</button></header>
189
+ <pre><code>/permission-status
190
+ /workspace-write</code></pre>
191
+ </div>
192
+ </div>
193
+ </article>
194
+
195
+ <article class="step">
196
+ <div>
197
+ <h3 id="chay-workflow">Chạy workflow</h3>
198
+ <p>Dùng command đúng mục tiêu để agent không phải diễn giải quá dài. Task nào nặng context thì dùng fresh session.</p>
199
+ <div class="command-card">
200
+ <header><span>Workflow</span><button class="clip-btn" data-clip="/task Implement the requested bounded change.">Lấy lệnh</button></header>
201
+ <pre><code>/task Implement the requested bounded change.
202
+ /review
203
+ /fresh-task Implement the requested bounded change.</code></pre>
204
+ </div>
205
+ </div>
206
+ </article>
207
+
208
+ <article class="step">
209
+ <div>
210
+ <h3 id="verify-truoc-khi-handoff">Verify trước khi handoff</h3>
211
+ <p>Final gate chỉ tin kết quả command đã chạy thật, exit 0, và khớp verify plan. Sau khi pin hoặc nâng version, chạy doctor trên project:</p>
212
+ <div class="command-card">
213
+ <header><span>Doctor</span><button class="clip-btn" data-clip="piagent-doctor">Lấy lệnh</button></header>
214
+ <pre><code>piagent-doctor</code></pre>
215
+ </div>
216
+ <p>Người phát triển chính platform còn có <span class="inline-code">npm run verify</span> trong source repo; chi tiết ở <a href="https://github.com/Vt-mmm/piagent/blob/main/CONTRIBUTING.md">CONTRIBUTING</a>.</p>
217
+ </div>
218
+ </article>
219
+
220
+ <article class="step">
221
+ <div>
222
+ <h3 id="go-cai-dat-khi-khong-dung-nua">Gỡ cài đặt khi không dùng nữa</h3>
223
+ <p><span class="inline-code">piagent-uninstall</span> mặc định chỉ in ra sẽ gỡ những gì rồi thoát; phải thêm <span class="inline-code">--apply</span> nó mới thực hiện, vì nó sửa Pi settings mà công cụ khác cũng ghi vào. Mặc định chỉ gỡ Pi package của platform; add-on, Pi host và state trong project đều là opt-in.</p>
224
+ <div class="command-card">
225
+ <header><span>Gỡ — hai lệnh</span><button class="clip-btn" data-clip="piagent-uninstall&#10;piagent-uninstall --apply">Lấy lệnh</button></header>
226
+ <pre><code>piagent-uninstall
227
+ piagent-uninstall --apply</code></pre>
228
+ </div>
229
+ <p>Add-on, Pi host, state trong project và helper npm-global đều tách riêng và là opt-in — <span class="inline-code">piagent-uninstall --help</span> liệt kê đủ. Nó gỡ theo những gì đang đăng ký trong Pi settings chứ không theo những gì bản hiện tại cài, nên package do release cũ đăng ký vẫn ra được.</p>
230
+ <div class="callout ok-callout">
231
+ <strong>Không bao giờ bị xoá</strong>
232
+ <p>Credential, trust, session, todo và <span class="inline-code">.pi/memory/</span> được giữ nguyên ở mọi tổ hợp cờ — đó là dữ liệu của người dùng, không phải state của platform. Các file sinh từ template rồi sửa tiếp như <span class="inline-code">AGENTS.md</span>, <span class="inline-code">.pi/settings.json</span>, <span class="inline-code">project-context.md</span> chỉ được liệt kê để tự quyết. Với <span class="inline-code">.pi/settings.json</span>, chỉ đúng entry trỏ tới platform bị bỏ khỏi <span class="inline-code">packages</span>.</p>
233
+ </div>
234
+ </div>
235
+ </article>
236
+
237
+ </div>
238
+ </section>
239
+ <nav class="pager" aria-label="Trang kế tiếp">
240
+ <a class="pager-prev" href="/">
241
+ <span class="pager-label">Trước</span>
242
+ <span class="pager-title">Overview</span>
243
+ </a>
244
+ <a class="pager-next" href="/scope">
245
+ <span class="pager-label">Tiếp</span>
246
+ <span class="pager-title">Phạm vi platform</span>
247
+ </a>
248
+ </nav>
249
+
250
+ <footer class="footer">
251
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
252
+ <div class="footer-links" aria-label="External links">
253
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
254
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
255
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
256
+ </div>
257
+ </footer>
258
+ </div>
259
+ </main>
260
+
261
+ <aside class="toc" aria-label="Mục lục trang">
262
+ <p class="toc-title">Trên trang này</p>
263
+ <nav data-toc></nav>
264
+ </aside>
265
+ </div>
266
+ </body>
267
+ </html>