feat(timer,time-log): 起錶配上停錶，並補登議題建立之前的時間
碼錶只在領取工作包時起動，所以工時報表上規劃與分析永遠是零。久了會讓人以為 規劃不花時間，而那正是估算失準最常見的來源。 timer 加上 --stop，而且**只停 --index 指的那一顆**。每個階段停掉自己起的那一支， 錶就不會跨階段跑——跑完就去開會而錶跑一整天，報表當場失真。反過來，別顆議題上的錶 一律不碰：Gitea 在別顆議題上起新錶會靜默地停掉並記錄前一顆，那種靜默結算正是領取鎖 那條規則當初要擋的，不能在這裡反過來製造它。錶本來就沒在跑不算失敗，這一步多半排在 回報之前，報成失敗只會讓人以為前面那件事沒做成而重跑一次。 time-log 補登議題建立之前那一段——讀齊輸入、逐項詢問、組出議題內容，往往是整個 plan 最耗時的部分，而那時候議題還不存在，沒有標的可起錶。長度由腳本自己算（議題的建立時間 減掉 --since），交給 agent 做減法等於讓兩邊的時鐘各算一次，而算錯了報表上看不出來。 **不設時間上限、照實補登**：中途去開會的兩小時會一起算進去，換來這個流程不必為此 多長一題出來問使用者。 補登不是冪等的動作，所以兩種情況跳過不補：錶已經跑在這顆議題上（補登排在起錶之前， 錶在跑就代表這一段補過了），以及這顆議題上已經有工時（整個流程跑完過一次）。工時記 重複比記不到更難在報表上被發現，所以判斷偏向不補。 時間追蹤在現有環境下可能是關著的，真實路徑跑不起來；兩支都靠 --dry-run 與 stub server 測，共 27 條。 議題 #57 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -0,0 +1,125 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* 補登一段沒有錶記到的工時。
|
||||
*
|
||||
* 規劃階段最耗時的那一段——讀齊輸入、逐項詢問、組出議題內容——發生在議題建立**之前**，
|
||||
* 那時候沒有標的可起錶（議題還不存在）。這段時間只能事後補登，否則報表上的規劃永遠是零，
|
||||
* 久了會讓人以為規劃不花時間，而那正是估算失準最常見的來源。
|
||||
*
|
||||
* **長度由這支腳本自己算**：議題的建立時間減掉 `--since`。交給 agent 做減法，等於讓
|
||||
* 兩邊的時鐘與時區各算一次，而算錯了報表上看不出來。
|
||||
*
|
||||
* **不設時間上限，照實補登。** 中途去開會的那兩個小時會一起被算進去——換來這個流程
|
||||
* 不必為此多長一題出來問使用者。時間記多了看得出來，記不到就永遠找不回來。
|
||||
*
|
||||
* 兩種情況跳過不補，因為補登一旦記兩遍，報表看不出來哪一筆是重複的：
|
||||
* - 自己的錶已經跑在這顆議題上：補登排在起錶之前，錶在跑就代表這一步做過了。
|
||||
* - 這顆議題上已經有自己的工時：整個流程跑完過一次了。
|
||||
*
|
||||
* 只寫工時，不動任何錶——別顆議題上有錶在跑也照補，那兩件事互不相干。
|
||||
*
|
||||
* 用法：
|
||||
* node scripts/time-log.js --repo owner/name --index 42 --since <ISO 8601 時間>
|
||||
* [--host <網址>] [--dry-run]
|
||||
*/
|
||||
import {
|
||||
ScriptError,
|
||||
expectOk,
|
||||
fetchIssue,
|
||||
giteaRequest,
|
||||
listIssueTimes,
|
||||
listStopwatches,
|
||||
main,
|
||||
parseFlags,
|
||||
parseIndex,
|
||||
parseRepo,
|
||||
preflight,
|
||||
resolveLogin,
|
||||
stopwatchOnIssue,
|
||||
} from './lib.js';
|
||||
|
||||
main(async () => {
|
||||
const flags = parseFlags(process.argv.slice(2), {
|
||||
required: ['repo', 'index', 'since'],
|
||||
optional: ['host'],
|
||||
booleans: ['dry-run'],
|
||||
});
|
||||
const repo = parseRepo(flags.repo);
|
||||
const index = parseIndex(flags.index);
|
||||
const since = parseSince(flags.since);
|
||||
const dryRun = flags['dry-run'] === true;
|
||||
const timesPath = `/repos/${repo}/issues/${index}/times`;
|
||||
|
||||
const login = resolveLogin({ host: flags.host });
|
||||
// 試跑照樣讀現況：手寫一份固定的清單會跟實作走鐘，也說不出「這一段已經補過了」
|
||||
if (!dryRun) await preflight(login, repo);
|
||||
const issue = await fetchIssue(login, repo, index);
|
||||
|
||||
const 建立時間 = Date.parse(issue.created_at);
|
||||
if (Number.isNaN(建立時間)) {
|
||||
throw new ScriptError(
|
||||
'NO_CREATED_AT',
|
||||
`${repo} 的議題 ${index} 沒有可解讀的建立時間，補登的長度算不出來`,
|
||||
);
|
||||
}
|
||||
|
||||
const 秒數 = Math.round((建立時間 - since) / 1000);
|
||||
const 略過 = await skipReason(login, repo, index, 秒數);
|
||||
const planned = 略過 === null ? [{ method: 'POST', path: timesPath, body: { time: 秒數 } }] : [];
|
||||
const 報告 = {
|
||||
repo,
|
||||
index: issue.number,
|
||||
title: issue.title,
|
||||
url: issue.html_url,
|
||||
since: new Date(since).toISOString(),
|
||||
議題建立時間: issue.created_at,
|
||||
秒數,
|
||||
補登: 略過 === null,
|
||||
...(略過 ? { note: 略過 } : {}),
|
||||
};
|
||||
|
||||
if (dryRun) {
|
||||
return { dryRun: true, ...報告, requests: planned };
|
||||
}
|
||||
|
||||
for (const { method, path, body } of planned) {
|
||||
expectOk(await giteaRequest(login, method, path, { body }), `${method} ${path}`);
|
||||
}
|
||||
|
||||
return 報告;
|
||||
});
|
||||
|
||||
/**
|
||||
* 不該補的理由，沒有就回 null。
|
||||
*
|
||||
* 三個理由都是「補了會比不補更錯」：長度非正的那一段根本不存在，另外兩個代表這一步
|
||||
* 已經做過，再補一次就是把同一段時間記兩遍。
|
||||
*/
|
||||
async function skipReason(login, repo, index, 秒數) {
|
||||
if (秒數 <= 0) {
|
||||
return '指令開始時間不早於議題建立時間，沒有可補登的區間；兩邊時鐘差幾秒是常事，這不算失敗。';
|
||||
}
|
||||
if (stopwatchOnIssue(await listStopwatches(login), repo, index)) {
|
||||
return '碼錶已經跑在這顆議題上。補登排在起錶之前，錶在跑就代表這一段補過了，不再記第二遍。';
|
||||
}
|
||||
if ((await listIssueTimes(login, repo, index)).length > 0) {
|
||||
return '這顆議題上已經有自己的工時紀錄，代表整個流程跑完過一次，不再補一次。';
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 解析 `--since`。擋在打 Gitea 之前：值打錯是最常見的輸入錯誤，
|
||||
* 而它在補登之前唯一的症狀就是長度不對，事後從報表上看不出來。
|
||||
* @returns {number} epoch 毫秒
|
||||
*/
|
||||
function parseSince(value) {
|
||||
const at = Date.parse(value);
|
||||
if (Number.isNaN(at)) {
|
||||
throw new ScriptError(
|
||||
'BAD_SINCE',
|
||||
`--since 需為可解析的 ISO 8601 時間（例如 2026-09-17T10:05:00Z），收到的是 ${value}`,
|
||||
);
|
||||
}
|
||||
return at;
|
||||
}
|
||||
+44
-19
@@ -1,18 +1,28 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* 起錶。
|
||||
* 起錶與停錶。
|
||||
*
|
||||
* 錶與領取鎖是兩件事：鎖用 assignee 加標籤（見 claim.js），錶只管工時。分開的理由是
|
||||
* 時機不同——鎖要在開工之前就上好，錶則要等到**工作樹真的建好之後**才起。工作樹建立
|
||||
* 失敗會中止整個領取，錶要是先起了，使用者就被計了一段什麼都沒做的時間，
|
||||
* 而工時要準正是工時報表的立足點。
|
||||
* 錶與領取鎖是兩件事：鎖用 assignee 加標籤（見 claim.js），錶只管工時。
|
||||
*
|
||||
* **領取工作包時**（sdlc-feat）兩者的時機不同：鎖要在開工之前就上好，錶則要等到
|
||||
* **工作樹真的建好之後**才起。工作樹建立失敗會中止整個領取，錶要是先起了，使用者就被
|
||||
* 計了一段什麼都沒做的時間，而工時要準正是工時報表的立足點。規劃與分析沒有工作樹，
|
||||
* 那條規則對它們不適用——它們的標的是需求議題本身，議題存在就起得了錶。
|
||||
*
|
||||
* 自己的錶跑在別顆議題上時擋下，不代勞停錶：那一段時間該記在哪顆議題上只有人知道，
|
||||
* 腳本自作主張會把工時記錯地方。錶已經跑在本議題上則什麼都不做——重新起錶會把已經
|
||||
* 累積的時間切成兩段，而中斷後重跑正是這支腳本最常見的處境。
|
||||
*
|
||||
* `--stop` 停錶，而且**只停 `--index` 指的那一顆**。每個階段停掉自己起的那支錶，
|
||||
* 錶就不會跨階段跑——跑完就去開會而錶跑一整天，報表當場失真。反過來，別顆議題上的錶
|
||||
* 一律不碰：Gitea 在別顆議題上起新錶會靜默地停掉並記錄前一顆，那種靜默結算正是
|
||||
* 領取鎖那條規則當初要擋的，這裡不能反過來製造它。
|
||||
*
|
||||
* 停錶時錶本來就沒在跑不算失敗：這一步多半排在別的事情做完之後（開完 PR、回報之前），
|
||||
* 把「本來就沒在跑」報成失敗，只會讓人以為前面那件事沒做成而重跑一次。
|
||||
*
|
||||
* 用法：
|
||||
* node scripts/timer.js --repo owner/name --index 40 [--host <網址>] [--dry-run]
|
||||
* node scripts/timer.js --repo owner/name --index 40 [--stop] [--host <網址>] [--dry-run]
|
||||
*/
|
||||
import {
|
||||
expectOk,
|
||||
@@ -25,6 +35,7 @@ import {
|
||||
parseRepo,
|
||||
preflight,
|
||||
resolveLogin,
|
||||
stopStopwatch,
|
||||
stopwatchElsewhere,
|
||||
stopwatchOnIssue,
|
||||
} from './lib.js';
|
||||
@@ -33,12 +44,13 @@ main(async () => {
|
||||
const flags = parseFlags(process.argv.slice(2), {
|
||||
required: ['repo', 'index'],
|
||||
optional: ['host'],
|
||||
booleans: ['dry-run'],
|
||||
booleans: ['stop', 'dry-run'],
|
||||
});
|
||||
const repo = parseRepo(flags.repo);
|
||||
const index = parseIndex(flags.index);
|
||||
const issuePath = `/repos/${repo}/issues/${index}`;
|
||||
const dryRun = flags['dry-run'] === true;
|
||||
const 要停錶 = flags.stop === true;
|
||||
|
||||
const login = resolveLogin({ host: flags.host });
|
||||
// 試跑照樣讀現況：手寫一份固定的清單會跟實作走鐘，也說不出「這顆已經在計時了」
|
||||
@@ -47,25 +59,38 @@ main(async () => {
|
||||
|
||||
const watches = await listStopwatches(login);
|
||||
const 已在計時 = stopwatchOnIssue(watches, repo, index) !== null;
|
||||
if (!已在計時 && watches.length > 0) throw stopwatchElsewhere(watches[0], '起錶');
|
||||
// 起錶才要擋：別顆議題上的錶會讓工時記錯地方。停錶只動這一顆，擋不擋都影響不到它
|
||||
if (!要停錶 && !已在計時 && watches.length > 0) throw stopwatchElsewhere(watches[0], '起錶');
|
||||
|
||||
// 已經在跑就不重起：重新起錶會把已經累積的時間切成兩段
|
||||
const planned = 已在計時 ? [] : [{ method: 'POST', path: `${issuePath}/stopwatch/start`, body: {} }];
|
||||
// 起錶：已經在跑就不重起，重新起錶會把已經累積的時間切成兩段
|
||||
// 停錶：沒在這顆上跑就沒得停，別顆議題上的錶不碰
|
||||
const 動作 = 要停錶
|
||||
? { 端點: 'stop', 要發請求: 已在計時 }
|
||||
: { 端點: 'start', 要發請求: !已在計時 };
|
||||
const planned = 動作.要發請求
|
||||
? [{ method: 'POST', path: `${issuePath}/stopwatch/${動作.端點}`, body: {} }]
|
||||
: [];
|
||||
|
||||
const 報告 = { repo, index: issue.number, title: issue.title, url: issue.html_url };
|
||||
|
||||
if (dryRun) {
|
||||
return { dryRun: true, repo, index, title: issue.title, requests: planned, 已在計時 };
|
||||
return { dryRun: true, ...報告, requests: planned, 已在計時 };
|
||||
}
|
||||
|
||||
if (要停錶) {
|
||||
// 端點回「沒有錶在跑」的狀態碼隨站台版本而異，所以停錶走 lib 那條容錯路徑；
|
||||
// 讀到的現況與實際狀態差一步（錶剛被別處停掉）也不該把整件事報成失敗
|
||||
const stopped = planned.length > 0 && (await stopStopwatch(login, repo, index));
|
||||
return {
|
||||
...報告,
|
||||
碼錶已停: stopped,
|
||||
...(stopped ? {} : { note: '碼錶本來就沒在這顆議題上運轉，這一步略過；別顆議題上的錶不由這裡代停。' }),
|
||||
};
|
||||
}
|
||||
|
||||
for (const { method, path, body } of planned) {
|
||||
expectOk(await giteaRequest(login, method, path, { body }), `${method} ${path}`);
|
||||
}
|
||||
|
||||
return {
|
||||
repo,
|
||||
index: issue.number,
|
||||
title: issue.title,
|
||||
url: issue.html_url,
|
||||
碼錶中: true,
|
||||
已在計時,
|
||||
};
|
||||
return { ...報告, 碼錶中: true, 已在計時 };
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user