Skip to content

Commit e6def42

Browse files
JamestsaiTWJamestsaiTW
authored
Merge pull request #7 from JamestsaiTW/website
Improve documentation visuals for web rendering
2 parents e7c62db + 5a2fc07 commit e6def42

9 files changed

Lines changed: 467 additions & 85 deletions

‎docs/01-why-tokens-matter.md‎

Lines changed: 23 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -51,23 +51,29 @@ Every token you send or receive has a cost. Here's how:
5151

5252
Understanding what Copilot does behind the scenes helps you optimize:
5353

54-
```text
55-
┌─────────────────────────────────────────────────┐
56-
│ Context Window │
57-
│ │
58-
│ ┌──────────────────┐ ┌─────────────────────┐ │
59-
│ │ INPUT TOKENS │ │ OUTPUT TOKENS │ │
60-
│ │ │ │ │ │
61-
│ │ System prompt │ │ The response │ │
62-
│ │ + copilot- │ │ you receive │ │
63-
│ │ instructions │ │ │ │
64-
│ │ + file context │ │ │ │
65-
│ │ + conversation │ │ │ │
66-
│ │ history │ │ │ │
67-
│ │ + YOUR prompt │ │ │ │
68-
│ └──────────────────┘ └─────────────────────┘ │
69-
└─────────────────────────────────────────────────┘
70-
```
54+
<div class="token-context-diagram" role="img" aria-label="Context window containing input tokens and output tokens">
55+
<div class="token-context-diagram__frame">
56+
<p class="token-context-diagram__title">Context Window</p>
57+
<div class="token-context-diagram__columns">
58+
<section class="token-context-diagram__panel">
59+
<h3>Input tokens</h3>
60+
<ul>
61+
<li>System prompt</li>
62+
<li><code>copilot-instructions.md</code></li>
63+
<li>File context</li>
64+
<li>Conversation history</li>
65+
<li>Your prompt</li>
66+
</ul>
67+
</section>
68+
<section class="token-context-diagram__panel token-context-diagram__panel--output">
69+
<h3>Output tokens</h3>
70+
<div class="token-context-diagram__panel-body">
71+
<p>The response you receive</p>
72+
</div>
73+
</section>
74+
</div>
75+
</div>
76+
</div>
7177

7278
- **System prompt:** Copilot's own instructions (you can't control this)
7379
- **`copilot-instructions.md`:** Your project-level instructions — loaded on **every** interaction

‎docs/01-why-tokens-matter.zh-TW.md‎

Lines changed: 23 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -51,23 +51,29 @@ Token 是大型語言模型讀寫時使用的基本單位。它不是單字，
5151

5252
了解 Copilot 背後實際做了什麼，才能知道該怎麼最佳化：
5353

54-
```text
55-
┌─────────────────────────────────────────────────┐
56-
│ Context Window │
57-
│ │
58-
│ ┌──────────────────┐ ┌─────────────────────┐ │
59-
│ │ INPUT TOKENS │ │ OUTPUT TOKENS │ │
60-
│ │ │ │ │ │
61-
│ │ System prompt │ │ 你收到的回應 │ │
62-
│ │ + copilot- │ │ │ │
63-
│ │ instructions │ │ │ │
64-
│ │ + file context │ │ │ │
65-
│ │ + conversation │ │ │ │
66-
│ │ history │ │ │ │
67-
│ │ + 你的 prompt │ │ │ │
68-
│ └──────────────────┘ └─────────────────────┘ │
69-
└─────────────────────────────────────────────────┘
70-
```
54+
<div class="token-context-diagram" role="img" aria-label="Context window containing input tokens and output tokens">
55+
<div class="token-context-diagram__frame">
56+
<p class="token-context-diagram__title">Context Window</p>
57+
<div class="token-context-diagram__columns">
58+
<section class="token-context-diagram__panel">
59+
<h3>輸入 token</h3>
60+
<ul>
61+
<li>System prompt</li>
62+
<li><code>copilot-instructions.md</code></li>
63+
<li>File context</li>
64+
<li>Conversation history</li>
65+
<li>你的 prompt</li>
66+
</ul>
67+
</section>
68+
<section class="token-context-diagram__panel token-context-diagram__panel--output">
69+
<h3>輸出 token</h3>
70+
<div class="token-context-diagram__panel-body">
71+
<p>你收到的回應</p>
72+
</div>
73+
</section>
74+
</div>
75+
</div>
76+
</div>
7177

7278
- **System prompt：** Copilot 自身的內建指示（你無法控制）
7379
- **`copilot-instructions.md`：** 專案層級指示，**每次互動都會載入**

‎docs/08-mcp-tool-costs.md‎

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -55,17 +55,24 @@ This isn't free. Each tool definition costs approximately:
5555

5656
Here's where it gets expensive:
5757

58-
```text
59-
Tools loaded = servers × tools_per_server × tokens_per_tool
60-
61-
Example (heavy setup):
62-
10 MCP servers × 5 tools each × 200 tokens avg = 10,000 tokens
63-
64-
Agent mode runs 5-25 steps per task.
65-
Tool definitions reload EVERY step.
66-
67-
10,000 tokens × 15 steps = 150,000 tokens just for tool definitions.
68-
```
58+
<div class="guide-visual" role="img" aria-label="Tool definition cost multiplies across servers, tools, and agent steps">
59+
<p class="guide-visual__title">Reloaded Tool Cost</p>
60+
<div class="guide-visual__grid guide-visual__grid--2">
61+
<section class="guide-visual__card">
62+
<h4>Formula</h4>
63+
<p class="guide-visual__math">Tools loaded = servers x tools_per_server x tokens_per_tool</p>
64+
<p class="guide-visual__note">That whole bundle reloads on every agent step.</p>
65+
</section>
66+
<section class="guide-visual__card">
67+
<h4>Heavy setup example</h4>
68+
<p class="guide-visual__math">10 MCP servers x 5 tools x 200 tokens = 10,000 tokens</p>
69+
<div class="guide-visual__flow">
70+
<p class="guide-visual__math">10,000 tokens x 15 steps</p>
71+
</div>
72+
<p class="guide-visual__metric">150,000 tokens</p>
73+
</section>
74+
</div>
75+
</div>
6976

7077
That's 150K tokens doing nothing but telling the agent what tools exist. Before any actual work happens.
7178

‎docs/08-mcp-tool-costs.zh-TW.md‎

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -47,15 +47,24 @@ Buffer: 40.4k (20%)
4747

4848
真正貴的是它會被重複載入：
4949

50-
```text
51-
Tools loaded = servers × tools_per_server × tokens_per_tool
52-
53-
Example:
54-
10 MCP servers × 5 tools × 200 tokens = 10,000 tokens
55-
56-
Agent mode 走 15 steps：
57-
10,000 × 15 = 150,000 tokens
58-
```
50+
<div class="guide-visual" role="img" aria-label="工具定義成本會隨 server、tool 與 agent 步數相乘">
51+
<p class="guide-visual__title">工具成本會一直重載</p>
52+
<div class="guide-visual__grid guide-visual__grid--2">
53+
<section class="guide-visual__card">
54+
<h4>公式</h4>
55+
<p class="guide-visual__math">Tools loaded = servers x tools_per_server x tokens_per_tool</p>
56+
<p class="guide-visual__note">整包工具定義會在每個 agent step 再載一次。</p>
57+
</section>
58+
<section class="guide-visual__card">
59+
<h4>重度設定範例</h4>
60+
<p class="guide-visual__math">10 MCP servers x 5 tools x 200 tokens = 10,000 tokens</p>
61+
<div class="guide-visual__flow">
62+
<p class="guide-visual__math">10,000 tokens x 15 steps</p>
63+
</div>
64+
<p class="guide-visual__metric">150,000 tokens</p>
65+
</section>
66+
</div>
67+
</div>
5968

6069
也就是說，還沒做任何真正工作，就先花了 15 萬個 token 讓 agent 知道有哪些工具可用。
6170

‎docs/09-comparisons-data.md‎

Lines changed: 30 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -151,15 +151,36 @@ Does compression hurt output quality? The research says: **rarely, and only at e
151151

152152
The savings curve is not linear. The first 30% of compression (dropping filler) is free. The next 20% (fragments, abbreviations) is nearly free. Beyond that, each additional compression point risks quality.
153153

154-
```text
155-
Savings vs. Quality Risk:
156-
157-
Quality ████████████████████████████████████░░░░░░░░░
158-
Risk ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░███████████████
159-
0% 20% 40% 60% 80%
160-
Token Savings →
161-
lite full ultra extreme
162-
```
154+
<div class="guide-visual" role="img" aria-label="Compression savings versus quality risk curve">
155+
<p class="guide-visual__title">Savings vs. Quality Risk</p>
156+
<div class="guide-visual__curve">
157+
<div class="guide-visual__curve-row">
158+
<span class="guide-visual__curve-label">Quality</span>
159+
<div class="guide-visual__curve-bar">
160+
<div class="guide-visual__curve-fill" style="width: 82%;"></div>
161+
</div>
162+
</div>
163+
<div class="guide-visual__curve-row">
164+
<span class="guide-visual__curve-label">Risk</span>
165+
<div class="guide-visual__curve-bar">
166+
<div class="guide-visual__curve-fill guide-visual__curve-fill--risk" style="width: 62%;"></div>
167+
</div>
168+
</div>
169+
</div>
170+
<div class="guide-visual__scale">
171+
<span>0%</span>
172+
<span>20%</span>
173+
<span>40%</span>
174+
<span>60%</span>
175+
<span>80%</span>
176+
</div>
177+
<div class="guide-visual__ticks">
178+
<span>lite</span>
179+
<span>full</span>
180+
<span>ultra</span>
181+
<span>extreme</span>
182+
</div>
183+
</div>
163184

164185
**Sweet spot: full caveman (30-50% input token savings; 40-55% output savings with terse system instructions).** Maximum return, negligible risk.
165186

‎docs/09-comparisons-data.zh-TW.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,37 @@
9999
再往後 20% 也通常很划算。
100100
超過那個點後，每多壓一點，都更可能帶來誤解。
101101

102+
<div class="guide-visual" role="img" aria-label="壓縮節省與品質風險的關係圖">
103+
<p class="guide-visual__title">效益與風險曲線</p>
104+
<div class="guide-visual__curve">
105+
<div class="guide-visual__curve-row">
106+
<span class="guide-visual__curve-label">品質</span>
107+
<div class="guide-visual__curve-bar">
108+
<div class="guide-visual__curve-fill" style="width: 82%;"></div>
109+
</div>
110+
</div>
111+
<div class="guide-visual__curve-row">
112+
<span class="guide-visual__curve-label">風險</span>
113+
<div class="guide-visual__curve-bar">
114+
<div class="guide-visual__curve-fill guide-visual__curve-fill--risk" style="width: 62%;"></div>
115+
</div>
116+
</div>
117+
</div>
118+
<div class="guide-visual__scale">
119+
<span>0%</span>
120+
<span>20%</span>
121+
<span>40%</span>
122+
<span>60%</span>
123+
<span>80%</span>
124+
</div>
125+
<div class="guide-visual__ticks">
126+
<span>lite</span>
127+
<span>full</span>
128+
<span>ultra</span>
129+
<span>extreme</span>
130+
</div>
131+
</div>
132+
102133
**建議甜蜜點：** Full caveman。
103134

104135
---

‎docs/10-practical-setup.md‎

Lines changed: 33 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -371,28 +371,39 @@ Each mode has a fundamentally different token cost profile:
371371

372372
Understanding the loop helps you minimize steps:
373373

374-
```text
375-
Step 1: Load context
376-
├── System prompt (~500 tokens)
377-
├── copilot-instructions.md (~50-1500 tokens)
378-
├── Tool definitions (~2,000-20,000 tokens)
379-
├── Conversation history (growing)
380-
└── YOUR prompt
381-
→ Send to LLM → Get response
382-
383-
Step 2: LLM decides to call a tool
384-
├── Tool call (function + params) → output tokens
385-
├── Tool result → input tokens (next step)
386-
└── Reasoning about result → output tokens
387-
388-
Step 3: Another tool call (or generate response)
389-
├── ALL of Step 1's context reloaded
390-
├── + Step 2's tool call and result
391-
└── + growing conversation
392-
→ Send to LLM again
393-
394-
... repeat 5-25 times
395-
```
374+
<div class="guide-visual" role="img" aria-label="Agent mode loop reloading context and tool calls across repeated steps">
375+
<p class="guide-visual__title">Agent Mode Loop</p>
376+
<div class="guide-visual__grid guide-visual__grid--3">
377+
<section class="guide-visual__card guide-visual__card--step">
378+
<h4><span class="guide-visual__step-label">Step 1:</span><span class="guide-visual__step-copy">Load context</span></h4>
379+
<ul class="guide-visual__list">
380+
<li>System prompt (~500 tokens)</li>
381+
<li><code>copilot-instructions.md</code> (~50-1500 tokens)</li>
382+
<li>Tool definitions (~2,000-20,000 tokens)</li>
383+
<li>Conversation history (growing)</li>
384+
<li>Your prompt</li>
385+
</ul>
386+
<p class="guide-visual__note">Send to LLM → get response</p>
387+
</section>
388+
<section class="guide-visual__card guide-visual__card--step">
389+
<h4><span class="guide-visual__step-label">Step 2:</span><span class="guide-visual__step-copy">Call tool</span></h4>
390+
<ul class="guide-visual__list">
391+
<li>Tool call (function + params) → output tokens</li>
392+
<li>Tool result → input tokens</li>
393+
<li>Reasoning about result → output tokens</li>
394+
</ul>
395+
</section>
396+
<section class="guide-visual__card guide-visual__card--step">
397+
<h4><span class="guide-visual__step-label">Step 3:</span><span class="guide-visual__step-copy">Repeat</span></h4>
398+
<ul class="guide-visual__list">
399+
<li>All of Step 1 context reloads</li>
400+
<li>+ prior tool call and result</li>
401+
<li>+ growing conversation</li>
402+
</ul>
403+
<p class="guide-visual__metric">Repeat 5-25 times</p>
404+
</section>
405+
</div>
406+
</div>
396407

397408
**Key insight:** Context grows with every step. Step 15 carries all the context from steps 1-14 plus the original prompt. This is why long agent sessions get expensive fast.
398409

‎docs/10-practical-setup.zh-TW.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,40 @@ Agent Mode 常比 Ask Mode 貴上很多倍。
234234

235235
每多一步，完整 context 都可能再重送一次，而且還會帶上前一步的結果，因此後期步驟會越來越貴。
236236

237+
<div class="guide-visual" role="img" aria-label="Agent Mode 會在多步驟中重複重送 context 與工具結果">
238+
<p class="guide-visual__title">Agent Mode 迴圈</p>
239+
<div class="guide-visual__grid guide-visual__grid--3">
240+
<section class="guide-visual__card guide-visual__card--step">
241+
<h4><span class="guide-visual__step-label">Step 1：</span><span class="guide-visual__step-copy">載入 context</span></h4>
242+
<ul class="guide-visual__list">
243+
<li>System prompt（約 500 tokens）</li>
244+
<li><code>copilot-instructions.md</code>（約 50-1500 tokens）</li>
245+
<li>Tool definitions（約 2,000-20,000 tokens）</li>
246+
<li>Conversation history（持續增加）</li>
247+
<li>你的 prompt</li>
248+
</ul>
249+
<p class="guide-visual__note">送進 LLM → 取得回應</p>
250+
</section>
251+
<section class="guide-visual__card guide-visual__card--step">
252+
<h4><span class="guide-visual__step-label">Step 2：</span><span class="guide-visual__step-copy">呼叫工具</span></h4>
253+
<ul class="guide-visual__list">
254+
<li>Tool call（function + params）→ output tokens</li>
255+
<li>Tool result → 下一步的 input tokens</li>
256+
<li>對結果做判斷 → output tokens</li>
257+
</ul>
258+
</section>
259+
<section class="guide-visual__card guide-visual__card--step">
260+
<h4><span class="guide-visual__step-label">Step 3：</span><span class="guide-visual__step-copy">再次重送</span></h4>
261+
<ul class="guide-visual__list">
262+
<li>Step 1 的 context 全部重載</li>
263+
<li>+ Step 2 的工具呼叫與結果</li>
264+
<li>+ 持續成長的對話內容</li>
265+
</ul>
266+
<p class="guide-visual__metric">重複 5-25 次</p>
267+
</section>
268+
</div>
269+
</div>
270+
237271
### 4.5.3 如何減少 Agent 步數
238272

239273
- **Prompt 要精準，並加上 acceptance criteria**

0 commit comments

Comments
 (0)